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

Entry points for uploaded 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
...

You can upload multiple functions in a single package, and functions within a single package can call each other, but functions can’t call functions within other packages. (They can call the handler functions, though.) For example, if you have a clean room where you upload two packages, each with a handler function and two helper functions:

• Code uploaded by either party (provider or consumer) can be run templates submitted by either party.

• A template can call function A or function B, but not A1, A2, B1, or 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.

Uploading a function with the same signature as one that you previously uploaded will overwrite the existing function, where a signature means the case-insensitive function name of an external handler, plus the data types of all its arguments, in the same order. Argument names are not part of the signature. You can’t overwrite a function uploaded by another account.

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.

Übersicht¶

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. The provider uploads a bundle by calling provider.load_python_into_cleanroom. You can either upload your code inline directly within that procedure, or upload a code file to a stage, then provide the stage location to that procedure.

   Although each bundle can include multiple functions, only one handler function is exposed for each upload. To expose multiple functions to templates, upload each handler separately or do a bulk upload (described below).

3. If the clean room is exposed externally, security checks are run before the code is installed in the clean room, and you must call provider.view_cleanroom_scan_status to confirm that security checks have passed before incrementing the default version.

4. After each successful upload, a new patch version of the clean room is generated. You must then increase the default version by calling provider.set_default_release_directive with the new patch number.

5. Create and upload a custom template that calls handlers in your code. The template must call the handler function using the cleanroom scope, that is: cleanroom.my_function(...).

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

Wichtige Hinweise zur Versionierung:¶

Every time the provider uploads a function, it increases the clean room patch number (and there is a limit of 99 patch numbers). Therefore, do your best to test and debug your code thoroughly before adding it to the clean room to reduce version updates during development.

You can upload multiple packages at once in a single bulk upload to reduce the number of patches generated. However, bulk uploads can make it more challenging to debug if the upload has a security scan issue, because the file that caused the problem isn’t reported in the error response.

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¶

You can upload Python files to a clean room stage and reference the stage when you call provider.load_python_into_cleanroom. Loading code from a stage allows you to develop the code in your local system in an editor, avoid copy/paste errors when loading it inline, and also have better versioning control of your source code. Note that you can upload multiple files in a single procedure call, but only one handler function is exposed for each upload.

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. To get the name of the stage for your clean room, call provider.get_stage_for_python_files. You must use the specified stage; you cannot use an arbitrary stage that you create.

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.

Uploading multiple Python functions in a single patch (bulk uploading)¶

If you want to upload multiple Python packages to your clean room, you can call prepare_python_for_cleanroom multiple times, then call load_prepared_python_into_cleanroom once to scan, upload, and generate a single patch for your clean room. The following example demonstrates uploading a UDF and a UDTF using bulk uploading:

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

Download the following examples and then upload them as worksheet files in your Snowflake account. You need separate accounts for the provider and consumer, each with the clean rooms API installed. Replace the information as noted in the sample files. See instructions to upload a SQL worksheet into your Snowflake account.

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

Download the following examples and then upload them as worksheet files in your Snowflake account. You need separate accounts for the provider and consumer, each with the clean rooms API installed. Replace the information as noted in the sample files. See instructions to upload a SQL worksheet into your Snowflake account.

• Consumer-written, consumer-run code: Provider worksheet

• Consumer-written, consumer-run code: Consumer worksheet

• Consumer-written, provider-run code: Provider worksheet

• Consumer-written, provider-run code: Consumer worksheet