Kundenspezifische Funktionen in einem Clean Room hochladen und ausführen¶

Übersicht¶

Sie können kundenspezifische Python UDFs und UDTFs in Ihren Clean Room hochladen und von Ihren Vorlagen aus ausführen, um komplexe Datenaktionen durchzuführen. Zu diesen Aktionen gehören maschinelles Lernen oder die kundenspezifische Datenmanipulation innerhalb einer Abfrage, als Teil eines Einzelschritts oder eines mehrstufigen Workflows. Python ist die einzige Codierungssprache, die kundenspezifische UDFs unterstützt.

Ihr hochgeladener Code kann Pakete aus einem genehmigten Bundle von Python-Paketen und der Snowpark-API importieren und verwenden.

Sowohl Anbieter als auch Verbraucher können kundenspezifischen Python-Code in einen Clean Room hochladen, obwohl der Prozess für Anbieter und Verbraucher unterschiedlich ist. Jedes Bundle mit hochgeladenem Code kann mehrere Funktionen definieren, die sich gegenseitig aufrufen, aber ein Bundle stellt nur eine Handler-Funktion zur Verfügung. Diese Handler-Funktion kann von Vorlagen aufgerufen werden, die von jedem erstellt oder ausgeführt werden, der den Clean Room nutzt. Wenn der Code interne Tabellen erstellt, kann auf diese Tabellen zugegriffen werden, wie unter Abläufe mit mehreren Schritten gestalten beschrieben.

Hochgeladener Code kann nicht gelöscht werden, aber er kann aktualisiert werden.

Auf dieser Seite erfahren Sie, wie Sie als Anbieter oder Verbraucher kundenspezifische Python-UDFs und UDTFs hochladen.

Vom Anbieter übermittelter Code¶

Vom Anbieter übermittelte Funktionen können als Inline-Code oder aus einem Snowflake-Stagingbereich hochgeladen werden. Beide Techniken werden hier vorgestellt.

Ihr hochgeladener Code kann Pakete aus einem genehmigten Satz von Python-Paketen hochladen und nativ importieren. Wenn Sie ein nicht standardmäßiges Paket benötigen, müssen Sie Snowpark Container Services in einem Clean Room verwenden, um Ihren Code zu hosten.

Sie können den hochgeladenen Code nicht einsehen, auch nicht Ihren eigenen Code. Stellen Sie also sicher, dass Sie eine Kopie von genau dem beilegen, was Sie in einen Clean Room hochladen.

Hier ist eine allgemeine Ansicht, wie ein Anbieter Code zu einem Clean Room hinzufügt:

1. Der Anbieter erstellt und konfiguriert den Clean Room auf normale Weise.

2. Der Anbieter lädt den Code hoch, indem er``provider.load_python_into_cleanroom`` aufruft. Sie können Ihren Code entweder inline direkt innerhalb dieses Prozesses hochladen oder eine Codedatei in einen Stagingbereich hochladen. Geben Sie anschließend den Stagingbereich für dieses Prozess an.

   Obwohl Ihr Code mehrere Funktionen enthalten kann, wird für jeden Upload nur ein Handler angezeigt. Um mehrere Funktionen in Vorlagen bereitzustellen, laden Sie jeden Handler hoch, indem Sie provider.load_python_into_cleanroom aufrufen.

3. Nach jedem erfolgreichen Hochladen des Codes wird eine neue Patchversion des Clean Rooms generiert. Sie müssen dann die Standardversion durch Aufruf von provider.set_default_release_directive auf die neue Patchnummer aktualisieren. Wenn der Clean Room extern zugänglich ist, werden vor der Installation Ihres Codes Sicherheitsprüfungen durchgeführt, und Sie müssen provider.view_cleanroom_scan_status aufrufen, um zu bestätigen, dass die Sicherheitsprüfungen bestanden wurden, bevor die Standardversion aktualisiert wird.

4. Sie erstellen eine kundenspezifische Vorlage, die Ihren Code aufruft und laden diese hoch. Die Vorlage ruft die Handler-Funktion über den cleanroom-Bereich auf: cleanroom.my_function. Beispiel: Eine Vorlage, die eine kundenspezifische simple_add-Funktion aufruft, die Sie hochgeladen haben, könnte wie folgt aussehen:

   SELECT cleanroom.simple_add(1, 2), cleanroom.simple_add({{ price | sqlsafe | int }}, {{ tax | sqlsafe | int }})
   

   Copy

5. Der Verbraucher führt Ihre Vorlage auf die gleiche Weise aus wie jede andere Vorlage.

   Tipp

   Wenn der Verbraucher bei der Installation eines Clean Rooms mit kundenspezifischem Code auf einen Fehler stößt, kann dies auf einen Syntaxfehler im Code hinweisen.

Codebeispiele, die diesen Ablauf demonstrieren, finden Sie im:ref:Abschnitt zu vom Anbieter geschriebenen Codebeispielen <label-dcr_provider_written_code_examples>.

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
$cleanroom_name,
'simple_add',                         -- Name used to call the UDF from a template.
['first INTEGER', 'second INTEGER'],  -- Arguments of the UDF, specified as '<variable_name> <SQL type>' pairs.
['numpy', 'pandas'],                  -- Packages imported by the UDF.
'INTEGER',                            -- SQL return type of UDF.
'add_two',                            -- Handler function in your code called when external name is called.
$$
import numpy as np   # Not used, but you can load supported packages.
import pandas as pd

def add_two(first, second):
    return first + second
$$
);

-- Save the following code as reverser.py:
--import numpy as np
--def main(some_string):
--  '''Return the reverse of a string plus a random number 1-10'''
--  return some_string[::-1] + str(np.random.randint(1,10))

-- Get the stage for your clean room.
CALL samooha_by_snowflake_local_db.provider.get_stage_for_python_files($cleanroom_name);

-- Save the file to the stage. Here is how to do it by using the Snowflake CLI
PUT file://~/reverser.py <STAGE_NAME> overwrite=True auto_compress=False;

-- Load the code from the stage into the clean room.
CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'reverse', -- Name used to call the function
    ['some_string  STRING'], -- Arguments and SQL types
    ['numpy'],               -- Any required packages
    ['/reverser.py'],        -- Relative path to file on stage
    'STRING',                -- Return type
    'reverser.main'          -- <FILE_NAME>.<FUNCTION_NAME>
);

-- Uploading code, even from a stage, increases the patch number.
CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name, 'V1_0', <NEW_PATCH_NUMBER>);

-- Upload a template that calls the function.
CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    $udf_template_name,
    $$
    SELECT
      p.status,
      cleanroom.reverse(p.status)
    FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS AS p
    LIMIT 100;
    $$
);

-- Switch to the consumer account and run the template to see the results.

Vom Verbraucher übermittelter Code¶

Ein Verbraucher kann UDF- oder UDTF-Code einreichen und von einer kundenspezifischen Vorlage aus aufrufen. Der vom Verbraucher hochgeladene Code wird zusammen mit einer kundenspezifischen Vorlage in einem einzigen Prozess gebündelt und mit einem einzigen Prozessaufruf hochladen. Der Verbrauchercode ist direkt an diese Vorlage gebunden und kann nicht von anderen Vorlagen aufgerufen werden.

Um Code als Verbraucher hochzuladen, sollten Sie die:doc:Syntax der kundenspezifischen Vorlage </user-guide/cleanrooms/demo-flows/custom-templates> und :ref:`das Übermitteln einer verbraucherspezifischen Vorlage <label-dcr_consumer_written_templates>`verstehen.

Beachten Sie, dass jeder Code, der von einem Verbraucher hochgeladen wird, für den Anbieter sichtbar sein kann, wenn dieser eine Berechtigung zum Hochladen anfragt. Der Verbraucher-Code ist auch sichtbar, wenn ein Anbieter oder Verbraucher die Vorlage untersucht.

Hier finden Sie einen Überblick über die Schritte zum Hochladen von kundenspezifischem Verbrauchercode:

1. Der Anbieter erstellt den Clean Room auf die übliche Weise und lädt dann den Verbraucher ein.

2. Der Verbraucher installiert und konfiguriert den Clean Room standardmäßig.

3. Der Verbraucher erstellt eine Vorlage. Die Vorlage ruft die UDF oder UDTF innerhalb des cleanroom-Namespace auf. Zum Aufrufen der verbraucherdefinierten calculate_tax-Funktion könnte eine einfache Vorlage wie der folgende Snippet aussehen:

   SELECT {{ cleanroom.calculate_tax(p.cost) }} AS Tax FROM my_db.my_sch.sales AS p;
   

   Copy

4. Der Verbraucher bereitet seinen Python-Code vor. Wir empfehlen die Verwendung von doppelten Anführungszeichen (" ") anstelle von einfachen Anführungszeichen (' ') in Ihrem Code, um zusätzliche Escapezeichen zu vermeiden, die später benötigt werden. Ihr Code kann auf ein Bundle mit ausgewählten Python-Bibliotheken verweisen.

5. Der Verbraucher übergibt seinen Python-Code an consumer.generate_python_request_template. Der Prozess gibt den Python-Code als gespeicherten Prozess zurück, mit einem Platzhalter für die kundenspezifische JinjaSQL-Vorlage. Es gibt mehrere mehrzeilige Zeichenfolgen in der Vorlage, die $$ als mehrzeilige Trennzeichen verwenden.

6. Ersetzen Sie den Platzhalter für die Vorlage in der Ausgabe von generate_python_request_template mit Ihrer JinjaSQL-Vorlage.

7. Maskieren Sie in der kombinierten Vorlage alle einfachen Anführungszeichen wie folgt: \'. Dies liegt daran, dass für die gesamte mehrzeilige Prozesszeichenfolge einfache Anführungszeichen als äußerstes Trennzeichen verwendet werden. Beispiel:

     BEGIN
   
     CREATE OR REPLACE FUNCTION CLEANROOM.custom_compare(min_status STRING, max_status STRING, this_status STRING)
     RETURNS boolean
     LANGUAGE PYTHON
     RUNTIME_VERSION = 3.10
     PACKAGES = (\'numpy\')
   
     HANDLER = \'custom_compare\'
     AS $$
     import numpy as np
   
     def custom_compare(min_status:str, max_status:str, this_status:str):
       statuses = [\'MEMBER\', \'SILVER\', \'GOLD\', \'PLATINUM\']
       return ((statuses.index(this_status) >= statuses.index(min_status)) &
               (statuses.index(this_status) <= statuses.index(max_status)))
     $$;
   
     -- Custom template
     LET SQL_TEXT varchar := $$
     SELECT
       c.status,
       c.hashed_email
     FROM IDENTIFIER( {{ my_table[0] }} ) as c
     WHERE cleanroom.custom_compare({{ min_status }}, {{ max_status }}, c.status);
     $$;
   
     LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
     RETURN TABLE(RES);
   
     END;
   

   Copy

8. Rufen Sie consumer.create_template_request mit Ihrer kombinierten Vorlage auf. Verwenden Sie einfache Anführungszeichen (' ') anstelle von doppelten Dollarzeichen als Trennzeichen ($$...$$), wenn Sie den Code für den gespeicherten Prozess im template_definition-Argument angeben. Beispiel:

   CALL samooha_by_snowflake_local_db.consumer.create_template_request(
     $cleanroom_name,
     $template_name,
     '
   BEGIN
   
   -- First, define the Python UDF.
   CREATE OR REPLACE FUNCTION CLEANROOM.custom_compare(min_status STRING, max_status STRING, this_status STRING)
   RETURNS boolean
   LANGUAGE PYTHON
   RUNTIME_VERSION = 3.10
   PACKAGES = (\'numpy\')
   
   HANDLER = \'custom_compare\'
   AS $$
   import numpy as np
   
   def custom_compare(min_status:str, max_status:str, this_status:str):
     statuses = [\'MEMBER\', \'SILVER\', \'GOLD\', \'PLATINUM\']
     return ((statuses.index(this_status) >= statuses.index(min_status)) &
             (statuses.index(this_status) <= statuses.index(max_status)))
       $$;
   
   -- Then define and execute the SQL query.
   LET SQL_TEXT varchar := $$
   SELECT
     c.status,
     c.hashed_email
   FROM IDENTIFIER( {{ my_table[0] }} ) as c
   WHERE cleanroom.custom_compare({{ min_status }}, {{ max_status }}, c.status);
   $$;
   
   -- Execute the query and then return the result.
   LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
   RETURN TABLE(RES);
   
   END;
   ');
   

   Copy

9. Verbraucher und Anbieter fahren mit dem standardmäßigen, vom Verbraucher definierten Vorlagenflow fort:

   1. Der Anbieter zeigt die Anforderung der Vorlage an (provider.list_pending_template_requests) und genehmigt sie dann durch Aufruf von approve_template_request. In der Anfrage kann der Anbieter die Vorlage und den gebündelten Code sehen.

   2. Der Verbraucher prüft den Status der Anfrage (consumer.list_template_requests) und, wenn der Status APPROVED lautet, führt er die Vorlage aus (consumer.run_analysis).