Hochladen und Verwenden von benutzerdefinierten Funktionen in Collaboration Clean Rooms¶

Einführung¶

Jeder Teilnehmende kann kundenspezifische Python-UDFs und UDTFs in eine Zusammenarbeit hochladen. Vorlagen in der Zusammenarbeit können diese Funktionen ausführen, um komplexe Datenaktionen durchzuführen. Zu den üblichen Verwendungszwecken gehören maschinelles Lernen oder die angepasste Datenmanipulation innerhalb einer Abfrage. Ihr hochgeladener Code kann Pakete aus einem genehmigten Bundle von Python-Paketen und den Snowpark API-Paketen importieren und verwenden.

Die folgenden Abschnitte zeigen, wie Sie eine benutzerdefinierte Funktion hochladen und verwenden.

Definieren und Verwenden von kundenspezifischen Code-Bundles¶

So laden Sie eine benutzerdefinierte Funktion hoch und verwenden sie:

Der Codeüberstellende:

1. Erstellt und registriert den Code durch Aufrufen von:ref:REGISTER_CODE_SPEC<label-dcr_collab_register_code_spec>.

   Der Code kann inline in der Spezifikation eingebettet sein oder über einen Stagingbereich verknüpft werden.

2. Erstellt eine Vorlage mit Verweis auf die Code-Bundle-Spezifikation anhand der ID im code_specs-Array der Vorlage. Fügen Sie dieses Feld als Peer der Felder „Vorlage“ und „Parameter“ hinzu, wie im folgenden Beispiel gezeigt:

   CopyExpand

    parameters:
      - name: <parameter_name>
        description: <parameter_description>
        required: <true_or_false>
        default: <default_value>
        type: <data_type>
   
    code_specs:             # Optional: List of code bundles used by this template
    - <code_spec_id>        # One or more code spec IDs.
   
    template: |
      <template_content>
   

   Show lessSee more

   Scroll to top

3. Registriert die Vorlage und verknüpft die Vorlage dann mit der Zusammenarbeit.

   Bemerkung

   Snowflake überprüft den hochgeladenen Code auf Sicherheitsprobleme. Wenn ein Sicherheitsproblem gefunden wird, werden der Code und die enthaltene Vorlage nicht zur Zusammenarbeit hinzugefügt.

Der Analyseausführende:

• Führt die Vorlage aus, indem er RUN als Standardmethode aufruft.

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_CODE_SPEC(
  $$
  api_version: 2.0.0
  spec_type: code_spec
  name: custom_udf
  version: v1
  functions:
    - name: normalize_value
      type: UDF
      language: PYTHON
      handler: normalize
      arguments:
        - name: value
          type: FLOAT
      returns: FLOAT
      code_body: |
        def normalize(value):
            return value / 100.0
  $$
);

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: normalization_template
  version: v1
  type: sql_analysis
  code_specs:
    - custom_udf_v1  -- Imports the code bundle.
  template: |
    SELECT cleanroom.custom_udf$normalize_value(metric, 0, 100)  -- Calls the UDF.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.ADD_TEMPLATE_REQUEST(
  'my_collaboration',
  'normalization_template_v1',
  ['consumer']
);

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: normalization_template
  version: v1
  type: sql_analysis
  code_specs:
    - custom_udf_v1  -- Bundle ID includes the version number.
  template: |
    SELECT cleanroom.custom_udf$normalize_value(metric, 0, 100)  -- Calls the UDF.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: normalization_template
  version: v2        -- Update the template version.
  type: sql_analysis
  code_specs:
    - custom_udf_v2  -- Use the new code bundle.
  template: |
    SELECT cleanroom.custom_udf$normalize_value(metric, 0, 100)  -- No change needed here.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

Code-Bundle-Spezifikation¶

Diese Spezifikation definiert ein Bundle von einer oder mehreren Codefunktionen oder Prozeduren, die von einer Vorlage aufgerufen werden können.

Eine Code-Bundle-Spezifikation enthält maximal 5 Funktionen plus Prozeduren.

Für Bezeichner in der Code-Bundle-Spezifikation gelten die folgenden allgemeinen Anforderungen:

• Namen: Müssen gültige Snowflake-Bezeichner sein, die mit einem Buchstaben beginnen und nur alphanumerische Zeichen und Unterstriche enthalten.

• Bezeichner in Anführungszeichen: Bezeichner in doppelten Anführungszeichen werden für Namen mit Sonderzeichen unterstützt.

• Unterscheidung nach Groß-/Kleinschreibung: Bei Bezeichnern ohne Anführungszeichen ist die Groß- und Kleinschreibung nicht relevant. Bei Bezeichnern in Anführungszeichen wird die Groß-/Kleinschreibung beibehalten.

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: code_spec            # Required: Must be "code_spec"
name: <identifier>              # Required: Unique name of this code bundle.
version: <version_id>           # Required: Alphanumeric with underscores (max 20 chars)
description: <description_text> # Optional: Description (max 1,000 chars)

artifacts:                      # Optional: Staged files for import
  - alias: <identifier>         # One or more artifact items...
    stage_path: <stage_path>    # Required: Full stage path. See below for additional requirements.
    description: <description_text>  # Optional: Description (max 500 chars)
    content_hash: <sha256_hash>      # Optional: SHA-256 hash for integrity verification

functions:                      # Required if no procedures defined
  - name: <identifier>          # One or more functions...
    type: UDF | UDTF            # Required: Function type
    language: PYTHON            # Required: Currently only PYTHON supported
    runtime_version: <python_version>  # Optional: Python runtime (3.10 - 3.14)
    handler: <handler>          # Required: Handler function
    arguments:                  # Optional: One or more function arguments
      - name: <arg_name>        # Argument name
        type: <sql_type>        # Snowflake SQL type of this argument
    returns: <sql_type>         # Required: Snowflake return type
    packages:                   # Optional: Package dependencies
      - <package_name>          # One or more package items...
    imports:                    # Optional: Artifact aliases to import
      - <artifact_alias>        # One or more import items...
    code_body: |                # Optional: Inline Python code (max 12 MB)
      <inline_python_code>
    description: <description_text>  # Optional: Description of this function.

procedures:                     # Required if no functions defined
  - name: <identifier>          # One or more procedure items...
    language: PYTHON            # Required: Currently only PYTHON supported
    runtime_version: <python_version>  # Optional: Python runtime version
    handler: <handler>          # Required: Handler function
    arguments:                  # Optional: One or more procedure arguments
      - name: <arg_name>        # Argument name
        type: <sql_type>        # Snowflake SQL type of this argument
    returns: <sql_type>         # Optional: Return type
    packages:                   # Optional: Package dependencies
      - <package_name>          # One or more package items...
    imports:                    # Optional: Artifact aliases to import
      - <artifact_alias>        # One or more import items...
    code_body: |                # Optional: Inline Python code
      # inline python_code ...
    description: <description_text>  # Optional: Description of this procedure.

api_version

Die verwendete Version der Collaboration API. Sie müssen 2.0.0 sein.

spec_type

Bezeichner des Spezifikationstyps. Sie müssen code_spec sein.

name: identifier

Ein eindeutiger Name für diese Code-Bundle-Spezifikation innerhalb dieser Registry. Muss ein gültiger Snowflake-Bezeichner mit maximal 75 Zeichen sein. Dies wird als Nachnamesegment verwendet, wenn Sie die Funktion in einer Vorlage aufrufen: cleanroom.code_spec_name$function_name

version: version_id

Kundenspezifischer Versionsbezeichner. Muss alphanumerisch mit Unterstrichen sein;maximal 20 Zeichen.

description: description_text (Optional)

Eine Beschreibung der Code-Bundle-Spezifikation (maximal 1.000 Zeichen).

artifacts (Optional)

Eine Liste der Stagingdateien oder -pakete, die von Ihren Funktionen oder Prozeduren importiert werden können, und optional über Handler-Funktionen verfügbar sind. Maximal 5 pro Spezifikation.

alias: identifier

Ein Alias zum Referenzieren dieses Artefakts in Importen. Wenn Sie innerhalb dieser Spezifikation auf diesen Alias verweisen, verwenden Sie den reinen Aliasnamen und nicht cleanroom.spec_name$alias; verwenden Sie also den reinen Funktionsnamen, um auf eine andere Funktion in dieser Spezifikation zu verweisen.

stage_path: stage_path

Vollständiger Stagingbereichspfad zur Artefaktdatei; Beispiel:@DB.SCHEMA.STAGE/path/file.whl.

• Der Stagingbereich muss ein interner Stagingbereich sein. Externe Stagingbereiche werden nicht unterstützt.

• Für den Stagingbereich muss DIRECTORY aktiviert sein: Für den Stagingbereich, der Artefakte enthält, muss DIRECTORY = TRUE festgelegt sein.

• Format des Stagingbereichspfads: Muss dem Format @[DB.]SCHEMA.STAGE/path/to/file.ext folgen.

• Kein Durchlaufpfad: Stagingbereichspfade dürfen nicht .. oder \ enthalten.

• Dieses Artefakt muss vorhanden sein: Die Datei muss im angegebenen Stagingbereichspfad vorhanden sein, wenn das Code-Bundle registriert wird.

• Für den Stagingbereich muss die serverseitigeSNOWFLAKE_SSE-Verschlüsselung aktiviert sein. Legen Sie beim Erstellen oder Ändern des Stagingbereichs ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE') fest.

• Wenn Sie eine Staging-Codedatei verschieben, löschen oder aktualisieren, müssen Sie ALTER STAGE stage name REFRESH aufrufen, um sicherzustellen, dass die Zusammenarbeit über die neuesten Informationen aus dem Stagingbereich verfügt. Code-Aktualisierungen werden nur unterstützt, bevor Sie die Code-Spezifikation registrieren, da an diesem Punkt die Version zugewiesen und die Hash-Prüfsumme berechnet wird.

description: description_text (Optional)

Eine Beschreibung des Artefakts (maximal 500 Zeichen).

content_hash: sha256_hash (Optional)

SHA-256 Hash für die Integritätsprüfung (64 Hexadezimalzeichen).

functions (Erforderlich, wenn keine Prozeduren definiert sind)

Eine Liste von UDF- oder UDTF-Definitionen.

name identifier

Der Funktionsname, der in der aufrufenden Vorlage angezeigt werden soll. Muss ein gültiger Snowflake-Bezeichner sein.

type

Der Funktionstyp. Eine der folgenden Optionen: UDF oder UDTF.

language

Die Programmiersprache der Funktion. Derzeit wird nur PYTHON unterstützt.

runtime_version: python_version (Optional)

Die zu verwendende Python-Laufzeitversion. Unterstützte Versionen: 3.10 bis 3.14.

handler: handler

Der Name der Handler-Funktion im Funktionscode, die aufgerufen werden soll, wenn name lautet.

arguments (Optional)

Funktionsargumente als Liste von Name-Typ-Paaren. Die Typen müssen gültige Snowflake-SQL-Typen sein.

returns: sql_type

Der Rückgabetyp. Verwenden Sie für UDFs einen SQL-Typ wie STRING oder FLOAT. Für UDTFs verwenden Sie TABLE(column_definitions):

packages (Optional)

Eine Liste der von diesem Code verwendeten Pakete. Dabei kann es sich um eines dieser Anaconda Python-Pakete oder dieser Snowpark API-Pakete handeln. Beispiel: snowflake-snowpark-python, numpy.

imports (Optional)

Eine Liste der zu importierenden Artefakte. Dies müssen Aliasse aus der Artefaktliste in dieser Spezifikation sein.

code_body (Optional)

Inline-Python-Code. Gegenseitig ausschließend mit Stagingimporten. Die maximale Größe beträgt 12 MB.

description: description_text (Optional)

Eine Beschreibung der Funktion (maximal 500 Zeichen).

procedures (Erforderlich, wenn keine Funktionen definiert sind)

Eine Liste der Definitionen der gespeicherten Prozeduren. Felder sind ähnlich wie bei functions, außer dass es kein type-Feld gibt.

API-Referenz¶

Die folgenden Prozeduren werden verwendet, um kundenspezifische Code-Bundles in einer Zusammenarbeit zu verwalten:

REGISTER_CODE_SPEC( ['<registry_name>' ,] <code_spec> )

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_CODE_SPEC(
  $$
  api_version: 2.0.0
  spec_type: code_spec
  name: custom_udf
  version: v1
  description: Custom UDF for data normalization

  functions:
    - name: normalize_value
      type: UDF
      language: PYTHON
      runtime_version: "3.10"
      handler: normalize
      arguments:
        - name: value
          type: FLOAT
        - name: min_val
          type: FLOAT
        - name: max_val
          type: FLOAT
      returns: FLOAT
      code_body: |
        def normalize(value, min_val, max_val):
            if max_val == min_val:
                return 0.0
            return (value - min_val) / (max_val - min_val)
  $$
);

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_CODE_SPEC(
  'my_custom_registry',
  $$
  api_version: 2.0.0
  spec_type: code_spec
  name: custom_udf
  version: v1
  description: Custom UDF for data normalization

  functions:
    - name: normalize_value
      type: UDF
      language: PYTHON
      runtime_version: "3.10"
      handler: normalize
      arguments:
        - name: value
          type: FLOAT
        - name: min_val
          type: FLOAT
        - name: max_val
          type: FLOAT
      returns: FLOAT
      code_body: |
        def normalize(value, min_val, max_val):
            if max_val == min_val:
                return 0.0
            return (value - min_val) / (max_val - min_val)
  $$
);

VIEW_REGISTERED_CODE_SPECS( [ '<registry_name>' ] )

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.VIEW_REGISTERED_CODE_SPECS();

VIEW_CODE_SPECS( <collaboration_name> )

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_CODE_SPECS(
  $collaboration_id
);

Beispielspezifikationen¶

api_version: 2.0.0
spec_type: code_spec
name: string_utils
version: v1
description: String utility functions

functions:
  - name: clean_string
    type: UDF
    language: PYTHON
    runtime_version: "3.10"
    handler: clean
    arguments:
      - name: input_str
        type: STRING
    returns: STRING
    description: Removes leading/trailing whitespace and converts to lowercase
    code_body: |
      def clean(input_str):
          if input_str is None:
              return None
          return input_str.strip().lower()

  - name: extract_domain
    type: UDF
    language: PYTHON
    runtime_version: "3.10"
    handler: extract
    arguments:
      - name: email
        type: STRING
    returns: STRING
    description: Extracts domain from email address
    code_body: |
      def extract(email):
          if email is None or '@' not in email:
              return None
          return email.split('@')[1]

api_version: 2.0.0
spec_type: code_spec
name: tokenizer
version: v1
description: Text tokenization UDTF

functions:
  - name: tokenize_text
    type: UDTF
    language: PYTHON
    runtime_version: "3.10"
    handler: Tokenizer
    arguments:
      - name: text
        type: STRING
      - name: delimiter
        type: STRING
    returns: TABLE(token STRING, position INTEGER)
    description: Splits text into tokens and returns each with its position
    code_body: |
      class Tokenizer:
          def process(self, text, delimiter):
              if text is None:
                  return
              tokens = text.split(delimiter if delimiter else ' ')
              for i, token in enumerate(tokens):
                  yield (token.strip(), i)

api_version: 2.0.0
spec_type: code_spec
name: ml_scoring
version: v2
description: ML scoring functions using custom library

artifacts:
  - alias: ml_lib
    stage_path: "@MY_DB.PUBLIC.CODE_STAGE/libs/ml_scoring_lib-1.0.0-py3-none-any.whl"
    description: Custom ML scoring library
    content_hash: "a1b2c3d4e5f6..."

functions:
  - name: predict_score
    type: UDF
    language: PYTHON
    runtime_version: "3.10"
    handler: ml_scoring_lib.predictor.predict
    arguments:
      - name: features
        type: ARRAY
    returns: FLOAT
    packages:
      - numpy
      - scikit-learn
    imports:
      - ml_lib
    description: Predicts score using trained ML model

api_version: 2.0.0
spec_type: code_spec
name: data_processor
version: v1
description: Data processing procedures

procedures:
  - name: aggregate_metrics
    language: PYTHON
    runtime_version: "3.10"
    handler: process
    arguments:
      - name: table_name
        type: STRING
      - name: group_column
        type: STRING
    returns: STRING
    packages:
      - snowflake-snowpark-python
    description: Aggregates metrics by specified column
    code_body: |
      def process(session, table_name, group_column):
          df = session.table(table_name)
          result = df.group_by(group_column).count()
          result.write.mode("overwrite").save_as_table("aggregated_results")
          return f"Aggregated {df.count()} rows into aggregated_results"

api_version: 2.0.0
spec_type: code_spec
name: analytics_suite
version: v3
description: Analytics suite with multiple modules

artifacts:
  - alias: utils
    stage_path: "@MY_DB.PUBLIC.CODE_STAGE/analytics/utils.py"
    description: Utility functions
  - alias: transformers
    stage_path: "@MY_DB.PUBLIC.CODE_STAGE/analytics/transformers.py"
    description: Data transformation functions
  - alias: validators
    stage_path: "@MY_DB.PUBLIC.CODE_STAGE/analytics/validators.py"
    description: Validation functions

functions:
  - name: transform_and_validate
    type: UDF
    language: PYTHON
    runtime_version: "3.10"
    handler: transformers.transform_validate
    arguments:
      - name: data
        type: OBJECT
    returns: OBJECT
    imports:
      - utils
      - transformers
      - validators
    description: Transforms and validates input data

Problembehandlung bei Code-Bundles¶

Fehler:

CodeSpecAlreadyExistsException

Ursache:

Code-Bundle-Spezifikation mit demselben Namen und bereits registrierter Version.

Lösung:

Verwenden Sie eine andere Version oder aktualisieren Sie die bestehende Version.

Fehler:

SpecValidationError

Ursache:

YAML stimmt nicht mit dem Schema überein.

Lösung:

Überprüfen Sie die erforderlichen Felder und das Format.

Fehler:

CodeSpecStageNotAccessibleError

Ursache:

Der in Artefakt referenzierte Stagingbereich ist nicht zugänglich.

Lösung:

Gewähren Sie Zugriff auf den Stagingbereich oder überprüfen Sie, ob der Stagingbereich vorhanden ist.

Fehler:

CodeSpecArtifactNotFoundAtStageError

Ursache:

Datei nicht im angegebenen Stagingbereichspfad gefunden.

Lösung:

Laden Sie die Datei vor der Registrierung in den Stagingbereich hoch.

Fehler:

StageDirectoryNotEnabledError

Ursache:

DIRECTORY ist nicht für den Stagingbereich aktiviert.

Lösung:

Aktivieren Sie das Verzeichnis für den Stagingbereich: ALTER STAGE ... SET DIRECTORY = (ENABLE = TRUE)

Fehler:

CodeSpecNotFoundForOwnerException

Ursache:

Vorlage verweist auf nicht registrierte Code-Bundle-Spezifikation.

Lösung:

Registrieren Sie die Code-Bundle-Spezifikation, bevor Sie die Vorlage registrieren.