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

Ausführen von hochgeladenem Code¶

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.

Wenn Sie z. B. eine Funktion mit dem Namen simple_add hochgeladen haben, die zwei numerische Parameter enthält, können Sie sie von einer Vorlage aus wie hier gezeigt aufrufen. Die Funktion wird immer mit dem Geltungsbereich``cleanroom`` referenziert. Eine Vorlage könnte zum Beispiel wie folgt simple_add aufrufen:

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

SELECT
  cleanroom.simple_add(
    {{ price | sqlsafe | int }}, {{ tax | sqlsafe | int }}
    ) AS TOTAL_ITEM_COST
...

Sie können mehrere Funktionen in ein einziges Paket hochladen, und Funktionen innerhalb eines einzelnen Pakets können sich gegenseitig aufrufen, aber Funktionen können keine Funktionen innerhalb anderer Pakete aufrufen. (Sie können jedoch die Handler-Funktionen aufrufen.) Beispiel:

Anmerkungen:

• Code, der von beiden Seiten (Anbietende und Verbrauchende) hochgeladen wird, kann von beiden Seiten ausgeführt werden.

• Eine Vorlage kann die Funktion A oder B aufrufen, aber nicht A1, A2, B1, B2.

• Funktion A kann Funktion B aufrufen und umgekehrt.

• Funktion A kann nicht B1 oder B2 aufrufen, und Funktion B kann nicht A1 oder A2 aufrufen.

• A1 kann A2 aufrufen und umgekehrt. A1 und A2 können B aufrufen. A1 und A2 können nicht B1 oder B2 aufrufen.

• B1 kann B2 aufrufen und umgekehrt. B1 und B2 können A aufrufen. B1 und B2 können nicht A1 oder A2 aufrufen.

Aktualisieren oder Löschen von kundenspezifischen Funktionen¶

Sie können eine bestehende Funktion oder Vorlage, die Sie hochgeladen haben, hochladen oder überschreiben, aber Sie können eine bestehende Funktion oder Vorlage nicht löschen. Die einzige Möglichkeit, eine Funktion zu „entfernen“, besteht darin, eine Dummy-Funktion mit genau demselben Namen und einer immer erfolgreichen Signatur zu erstellen.

Wenn Sie eine Funktion mit genau derselben Signatur hochladen, wie die zuvor hochgeladene Funktion, wird die vorhandene Funktion überschrieben. Die Signatur steht für den Funktionsnamen des externen Handlers, bei dem die Groß- und Kleinschreibung nicht berücksichtigt wird, sowie für die Datentypen aller Parameter in der gleichen Reihenfolge. Parameternamen spielen keine Rolle. Sie können eine Funktion, die von einem anderen Konto hochgeladen wurde, nicht überschreiben.

Da die Signatur beim Aktualisieren einer Funktion übereinstimmen muss, können Sie die Signatur einer vorhandenen Funktion nicht ändern. Wenn Sie die Funktion foo(name VARIANT age INTEGER) und dann die Funktion foo(name VARIANT age FLOAT) hochladen, wird dem Clean Room zusätzlich zur ersten Funktion die zweite Funktion hinzugefügt, da sich die Argumenttypen unterscheiden.

Wichtige Hinweise zur Versionierung:¶

Jedes Mal, wenn der Anbieter eine Funktion hochlädt, erhöht er die Patchnummer (und es gibt ein Limit von 99 Patchnummern). Geben Sie daher Ihr Bestes, um Ihren Code gründlich zu testen und zu debuggen, bevor Sie ihn in den Clean Room aufnehmen, um Versionsaktualisierungen während der Entwicklung zu reduzieren.

Wenn Sie eine Patchnummer aktualisieren, müssen Kunden, die die Clean Room UI verwenden möglicherweise die Seite aktualisieren, um die Änderung zu sehen. Kunden, die die API verwenden, sollte Änderungen sofort sehen. Je nach, je nach den verfügbaren Ressourcen kann es aber zu einer Verzögerung kommen. Erfahren Sie mehr über die Versionierung von Clean Rooms.

Vom Anbieter geschriebenen Inline-Funktionen hochladen¶

Sie können den Code inline im``code`` Parameter provider.load_python_into_cleanroom hochladen. Hier ist ein Beispiel für das Hochladen einer einfachen Funktion inline:

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
$$
);

Die aufrufende Vorlage ruft diese Funktion über cleanroom.simple_add auf. Beispiele von Anbietern zeigen, wie Inline-Code hochgeladen wird.

Vom Anbieter geschriebene Funktionen aus einem Stagingbereich hochladen¶

Sie können Python-Dateien in einen Clean Room-Stagingbereich hochladen und auf den Stagingbereich verweisen, wenn Sie provider.load_python_into_cleanroom aufrufen. Durch das Laden von Code aus einem Stagingbereich können Sie den Code in Ihrem lokalen System in einem Editor entwickeln, Sie vermeiden Kopier-/Einfügefehler beim Inline-Laden, und Sie haben außerdem eine bessere Versionskontrolle. Beachten Sie, dass Sie mehrere Dateien mit einem einzigen Prozessaufruf hochladen können, aber für jeden Upload nur eine Handler-Funktion verfügbar ist.

Der Code wird von einem Stagingbereich in den Clean Room geladen, wenn Sie load_python_into_cleanroom aufrufen. Spätere Änderungen am Code im Stagingbereich werden nicht an den Clean Room weitergegeben.

Hochladen Ihres UDF in einen Stagingbereich:

1. Erstellen Sie Ihre .py-Datei, und stellen Sie sie an einem Speicherort zur Verfügung, an dem Sie sie in einen Snowsight-Stagingbereich hochladen können.

2. Um den Namen des Stagingbereichs für Ihren Clean Room zu erhalten, rufen Sie provider.get_stage_for_python_files($cleanroom_name) auf. Dieser Stagingbereich ist über den Clean Room zugänglich – Sie können keinen beliebigen Stagingbereich verwenden, den Sie erstellen.

3. Laden Sie die .py-Datei in den Stagingbereich Ihres Clean Rooms hoch. Es gibt mehrere Möglichkeiten, dies zu tun, einschließlich der Verwendung der CLI, von Snowsight oder sprachspezifischer Treiber.

4. Rufen Sie provider.load_python_into_cleanroom mit dem Stagingbereich, dem Handler, dem externen Namen, Argumenten und dem Rückgabetyp auf. Vorlagen in Ihrem Clean Room können jetzt die Funktion aufrufen.

Der folgende Beispielcode zeigt, wie Sie Code aus einem Stagingbereich in einen Clean Room laden.

-- 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.

Beispiele von Anbietern zeigen das Hochladen von Code aus einem Stagingbereich.

Problembehandlung bei Syntax-Fehlern oder Scan-Fehlern im hochgeladenen Code¶

Wenn Sie eine Funktion hochladen, die aufgrund eines Syntaxfehlers fehlschlägt, oder wenn ein Sicherheitsscan fehlschlägt, kann ein nicht veröffentlichbarer Patch generiert werden. Daher sollten Sie Ihren Code vor dem Hochladen gründlich testen, damit er keine Syntaxfehler enthält.

Sie können die Liste der Pakete und deren Überprüfungsstatus anzeigen, indem Sie den folgenden SQL-Befehl ausführen, der die Clean Room-ID an der angegebenen Stelle bereitstellt:

SHOW VERSIONS IN APPLICATION PACKAGE samooha_cleanroom_cleanroom_id;

Sicherheitsscans¶

Nach jeder Aktion, die eine neue Patchversion in einem externen Clean Room erzeugt, wird ein Sicherheitsscan durchgeführt, z. B. wenn die Anbietenden Python in den Clean Room hochladen. (Der auf dieser Seite beschriebene, von Verbrauchenden übermittelte Code löst keinen Sicherheitsscan aus.) In internen Clean Rooms werden keine Sicherheitsscans durchgeführt, aber wenn Sie einen internen Clean Room in einen externen Clean Room ändern, wird ein Sicherheitsscan für diesen Patch ausgelöst. Ein Clean Room-Patch kann erst dann extern veröffentlicht werden, wenn er gescannt wurde.

Data Clean Rooms verwendet das Sicherheitsscan-Framework der Snowflake Native App. Befolgen Sie die Best Practices für die Sicherheit der Native App, um Fehler mit dem Sicherheitsscan zu vermeiden.

Sie können weitere Aktionen zur Erstellung von Patches durchführen, bevor der letzte Sicherheitsscan abgeschlossen ist. Sie müssen jedoch darauf warten, dass provider.view_cleanroom_scan_status erfolgreich beendet ist, bevor Sie die Standard Release-Richtlinie aktualisieren können. Danach können Sie die neueste Clean Room-Version bereitstellen.

Hochladen mehrerer Python-Funktionen in einen einzigen Patch¶

Wenn Sie mehrere über Vorlagen aufrufbare Python Pakete in Ihren Reinraum hochladen möchten, können Sie prepare_python_for_cleanroom mehrmals aufrufen und anschließend einmal load_prepared_python_into_cleanroom aufrufen, um einen einzigen Patch für Ihren Clean Room zu scannen, hochzuladen und zu generieren. Das folgende Beispiel zeigt das Hochladen einer UDF und UDTF mithilfe von Massen-Uploads:

---- Add custom inline UDF ----
CALL samooha_by_snowflake_local_db.provider.prepare_python_for_cleanroom(
    $cleanroom_name,
    'get_next_status',  -- Name of the UDF. Can be different from the handler.
    ['status VARCHAR'], -- Arguments of the UDF, specified as (variable name, SQL type).
    ['numpy'],          -- Packages needed by UDF.
    [],                 -- When providing the code inline, this is an empty array.
    'VARCHAR',          -- Return type of UDF.
    'get_next_status',  -- Handler.
    $$
import numpy as np
def get_next_status(status):
  """Return the next higher status, or a random status
  if no matching status found or at the top of the list."""

  statuses = ['MEMBER', 'SILVER', 'GOLD', 'PLATINUM', 'DIAMOND']
  try:
    return statuses[statuses.index(status.upper()) + 1]
  except:
    return 'NO MATCH'
    $$
);

---- Add custom inline UDTF. ----
CALL samooha_by_snowflake_local_db.provider.prepare_python_for_cleanroom(
    $cleanroom_name,
    'get_info',  -- Name of the UDTF. Can be different from the handler.
    ['hashed_email VARCHAR', 'days_active INT', 'status VARCHAR', 'income VARCHAR'],   -- Name/Type arguments of the UDTF.
    ['numpy'],         -- Packages used by UDTF.
    [],                -- When providing the code inline, this is an empty array.
    'TABLE(hashed_email VARCHAR, months_active INT, level VARCHAR)',  -- Return type of UDTF.
    'GetSomeVals',     -- Handler class name.
$$
class GetSomeVals:
  def __init__(self):
    self.month_days = 30

  def process(self, hashed_email, days_active, status, income):
    '''Change days into rough months, and also return whether we
    think the user's membership status is lower, higher, or equal to
    what is expected, based on their income.'''

    months_active = days_active // self.month_days
    brackets = ['0-50K', '50K-100K', '100K-250K', '250K+']
    statuses = ['MEMBER', 'SILVER', 'GOLD', 'PLATINUM']
    if(statuses.index(status) < brackets.index(income)):
      level = 'low'
    elif(statuses.index(status) > brackets.index(income)):
      level = 'high'
    else:
      level = 'equal'

    yield(hashed_email, months_active, level)
$$
);

-- Upload all stored procedures.
-- Note the new patch number returned by this procedure. Keep this number for later use.
CALL samooha_by_snowflake_local_db.provider.load_prepared_python_into_cleanroom($cleanroom_name);

-- Set the release directive specified by the last load_python_into_cleanroom call.
CALL samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', <PATCH_NUMBER>);

Vom Anbieter geschriebene Codebeispiele¶

Die folgenden Beispiele zeigen das Hinzufügen von vom Anbieter geschriebenen UDFs und UDTFs zu einem Clean Room.

Laden Sie die folgenden Beispiele herunter, und laden Sie sie dann als Arbeitsblattdateien in Ihr Snowflake-Konto hoch. Sie benötigen separate Konten für den Anbieter und den Verbraucher, jeweils mit einer installierten Clean Room API. Ersetzen Sie die Informationen wie in den Beispieldateien notiert.

• Beispielcode des Anbieters

• Beispielcode für Verbraucher

• Laden einer Datei aus einem Stagingbereich. Führen Sie dieses Notebook aus, nachdem Sie das Anbieterbeispiel ausgeführt haben, um zu versuchen, eine UDF aus einem Stagingbereich zu laden.

• Hochladen mehrerer Python-Funktionen in einen einzigen Patch. Dies ist ein Clean Room für interne Tests mit einem Konto. Sie können dasselbe Konto für die Rolle von Anbietenden und Verbrauchenden verwenden.

Verbraucher-Codebeispiele¶

Die folgenden Beispiele zeigen das Hinzufügen von vom Anbieter geschriebenen UDFs zu einem Clean Room.

Laden Sie die folgenden Beispiele herunter, und laden Sie sie dann als Arbeitsblattdateien in Ihr Snowflake-Konto hoch. Sie benötigen separate Konten für den Anbieter und den Verbraucher, jeweils mit einer installierten Clean Room API. Ersetzen Sie die Informationen wie in den Beispieldateien notiert:

• Beispielcode des Anbieters

• Beispielcode für Verbraucher

• Von Verbrauchenden verfasster und von Anbietenden ausgeführter Code: Anbietenden-Notizbuch

• Von Verbrauchenden verfasster und von Anbietenden ausgeführter Code: Verbrauchenden-Notizbuch