Schreiben von gespeicherten Prozeduren in Python¶

Einschränkungen¶

In dieser Vorschau bestehen für gespeicherte Snowpark-Prozeduren die folgenden Einschränkungen:

• Das Erstellen von Prozessen wird in gespeicherten Prozeduren nicht unterstützt.

• Das Ausführen paralleler Abfragen wird in gespeicherten Prozeduren nicht unterstützt.

• Sie können keine APIs verwenden, die PUT/GET-Befehle ausführen, einschließlich Session.sql("PUT ...") und Session.sql("GET ...").

• Beim Herunterladen von Dateien aus einem Stagingbereich mit session.file.get wird die Mustererkennung nicht unterstützt.

• Wenn Sie Ihre gespeicherte Prozedur über eine Aufgabe ausführen, müssen Sie beim Erstellen der Aufgabe ein Warehouse angeben. Sie können zum Ausführen der Aufgabe keine von Snowflake verwalteten Computeressourcen verwenden.

• Das Erstellen benannter temporärer Objekte wird in einer gespeicherten Prozedur mit Eigentümerrechten nicht unterstützt. Eine gespeicherte Prozedur mit Eigentümerrechten ist eine gespeicherte Prozedur, die mit den Berechtigungen des Eigentümers der gespeicherten Prozedur ausgeführt wird. Weitere Informationen dazu finden Sie unter Aufruferrechte oder Eigentümerrechte.

Planen des Schreibens Ihrer gespeicherten Prozedur¶

Gespeicherte Prozeduren werden innerhalb von Snowflake ausgeführt. Daher müssen Sie den Code, den Sie schreiben, unter Berücksichtigung dieser Tatsache planen.

• Begrenzen Sie den Verbrauch von Arbeitsspeicher. Snowflake belegt Methoden mit einer Begrenzung hinsichtlich der benötigten Menge an Arbeitsspeicher. Weitere Hinweise dazu finden Sie unter Entwerfen von Handlern unter Berücksichtigung der Snowflake-bedingten Einschränkungen.

• Stellen Sie sicher, dass Ihre Handler-Methode oder Funktion threadsicher ist.

• Befolgen Sie die Regeln und Sicherheitsbeschränkungen. Weitere Informationen dazu finden Sie unter Sicherheitsverfahren für UDFs und Prozeduren.

• Entscheiden Sie, ob Sie die gespeicherte Prozedur mit Aufruferrechten oder mit Eigentümerrechten ausführen möchten.

• Berücksichtigen Sie die „snowflake-snowpark-python“-Version, die zum Ausführen gespeicherter Prozeduren verwendet wird. Aufgrund von Einschränkungen im Freigabeprozess von gespeicherten Prozeduren liegt die Version der „snowflake-snowpark-python“-Bibliothek, die in der Umgebung für die gespeicherte Python-Prozedur verfügbar ist, normalerweise eine Version hinter der öffentlich freigegebenen Version zurück. Verwenden Sie folgende SQL, um die neueste verfügbare Version zu ermitteln:

  select * from information_schema.packages where package_name = 'snowflake-snowpark-python' order by version desc;
  

  Copy

Schreiben der Methode oder Funktion¶

Beachten Sie beim Schreiben der Methode oder Funktion für die gespeicherte Prozedur Folgendes:

• Geben Sie das Snowpark-Session-Objekt als erstes Argument Ihrer Methode oder Funktion an. Wenn Sie Ihre gespeicherte Prozedur aufrufen, erstellt Snowflake automatisch ein Session-Objekt und übergibt dieses an Ihre gespeicherte Prozedur. (Sie können das Session-Objekt nicht selbst erstellen.)

• Für die restlichen Argumente und für den Rückgabewert werden die Python-Typen verwendet, die den Snowflake-Datentypen entsprechen. Snowflake unterstützt die Python-Datentypen, die unter SQL-Python-Zuordnung von Datentypen für Parameter und Rückgabetypen aufgelistet sind.

Fehlerbehandlung¶

Sie können die üblichen Python-Techniken zur Ausnahmebehandlung verwenden, um Fehler innerhalb der Prozedur abzufangen.

Wenn innerhalb der Methode eine Ausnahme auftritt, die nicht von der Methode abgefangen wird, gibt Snowflake einen Fehler aus, der den Stacktrace für die Ausnahme enthält. Wenn die Protokollierung von unbehandelten Ausnahmen aktiviert ist, protokolliert Snowflake Daten zu unbehandelten Ausnahmen in einer Ereignistabelle.

Abhängigkeiten für Code zur Verfügung stellen¶

Wenn Ihr Handler-Code von Code abhängt, der außerhalb des Handlers selbst definiert ist (z. B. in einem Modul definierter Code) oder von Ressourcendateien, können Sie diese Abhängigkeiten für Ihren Code zur Verfügung stellen, indem Sie ihn in einen Stagingbereich hochladen. Weitere Informationen dazu finden Sie unter Abhängigkeiten für Code zur Verfügung stellen und für Python-Arbeitsblätter unter Python-Datei aus einem Stagingbereich zu einem Arbeitsblatt hinzufügen.

Wenn Sie Ihre gespeicherte Prozedur mit SQL erstellen, verwenden Sie beim Schreiben der CREATE PROCEDURE-Anweisung die IMPORTS-Klausel, um auf die Abhängigkeitsdateien zu verweisen.

Zugriff auf Daten in Snowflake über Ihre gespeicherte Prozedur¶

Um auf Daten in Snowflake zuzugreifen, verwenden Sie die Snowpark-Bibliotheks-APIs.

Bei der Verarbeitung eines Aufrufs Ihrer gespeicherten Python-Prozedur erstellt Snowflake ein Snowpark-Session-Objekt und übergibt das Objekt an die Methode oder Funktion für Ihre gespeicherte Prozedur.

Wie bei gespeicherten Prozeduren in anderen Sprachen wird der Kontext für die Sitzung (z. B. die Berechtigungen, die aktuelle Datenbank, das aktuelle Schema usw.) dadurch bestimmt, ob die gespeicherte Prozedur mit Aufruferrechten oder mit Eigentümerrechten ausgeführt wird. Weitere Details dazu finden Sie unter Accessing and Setting the Session State.

Sie können dieses Session-Objekt verwenden, um APIs in der Snowpark-Bibliothek aufzurufen. Sie können zum Beispiel einen DataFrame für eine Tabelle erstellen oder eine SQL-Anweisung ausführen.

Weitere Informationen dazu finden Sie im Snowpark-Entwicklerhandbuch.

def run(session, from_table, to_table, count):

  session.table(from_table).limit(count).write.save_as_table(to_table)

  return "SUCCESS"

Lesen von Dateien¶

Mit der Klasse SnowflakeFile des Snowpark-Moduls snowflake.snowpark.files können Sie dynamisch eine Datei aus einem Stagingbereich mit Ihrem Python-Handler lesen.

Snowflake unterstützt das Lesen von Dateien mit SnowflakeFile sowohl für gespeicherte Prozeduren als auch für benutzerdefinierte Funktionen. Weitere Informationen zum Lesen von Dateien mit Ihrem Handler-Code sowie weitere Beispiele finden Sie unter Lesen einer Datei mit einem Python-UDF-Handler.

Dieses Beispiel zeigt, wie Sie eine gespeicherte Prozedur mit Eigentümerrechten, die eine Datei mit der Klasse SnowflakeFile liest, erstellen und aufrufen.

Erstellen Sie die gespeicherte Prozedur mit einem Inline-Handler, und geben Sie den Eingabemodus als binär an, indem Sie rb als mode-Argument übergeben:

CREATE OR REPLACE PROCEDURE calc_phash(file_path string)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python','imagehash','pillow')
HANDLER = 'run'
AS
$$
from PIL import Image
import imagehash
from snowflake.snowpark.files import SnowflakeFile

def run(ignored_session, file_path):
    with SnowflakeFile.open(file_path, 'rb') as f:
        return imagehash.average_hash(Image.open(f))
$$;

Rufen Sie die gespeicherte Prozedur auf:

CALL calc_phash(build_scoped_file_url(@my_files, 'my_image.jpg'));

Verwenden von Drittanbieterpaketen aus Anaconda¶

Sie können beim Erstellen von gespeicherten Prozeduren in Python angeben, dass Anaconda-Pakete installiert werden sollen. Eine Liste der Drittanbieterpakete von Anaconda finden Sie im Anaconda-Snowflake-Kanal. Diese Drittanbieter-Pakete werden von Anaconda erstellt und bereitgestellt. Sie können den Snowflake-Conda-Kanal für lokale Tests und Entwicklung kostenlos auf Grundlage der ergänzenden Bedingungen für eingebettete Software in den Anaconda-Nutzungsbedingungen verwenden.

Informationen zu bestehenden Einschränkungen finden Sie unter Einschränkungen.

Erste Schritte¶

Bevor Sie die von Anaconda in Snowflake bereitgestellten Pakete verwenden können, müssen Sie die Snowflake-Bedingungen für Drittanbieter anerkennen.

1. Melden Sie sich bei Snowsight an.

2. Wählen Sie Admin » Billing & Terms aus.

3. Wählen Sie im Abschnitt Anaconda die Option Enable aus.

4. Klicken Sie im Anaconda Packages-Dialog auf den Link, um die Snowflake-Bedingungen für Drittanbieter zu prüfen.

5. Wenn Sie mit den Bedingungen einverstanden sind, klicken Sie auf Acknowledge & Continue.

Wenn Sie beim Versuch, die Nutzungsbedingungen zu akzeptieren, eine Fehlermeldung erhalten, fehlt in Ihrem Benutzerprofil möglicherweise ein Vorname, ein Nachname oder eine E-Mail-Adresse. Wenn Sie eine Administratorrolle haben, finden Sie unter Benutzerdetails zum Benutzerprofil hinzufügen entsprechende Informationen zum Aktualisieren Ihres Profils in Snowsight. Wenden Sie sich andernfalls an einen Administrator, um Ihr Konto zu aktualisieren.

Anzeigen und Verwenden von Paketen¶

Sie können alle verfügbaren Pakete und deren Versionsinformationen anzeigen, indem Sie die Information Schema-Ansicht PACKAGES abfragen:

select * from information_schema.packages where language = 'python';

Weitere Informationen dazu finden Sie in der Snowflake-Dokumentation zu Python-UDFs unter Verwenden von Drittanbieterpaketen.

Erstellen einer gespeicherten Python-Prozedur zum Automatisieren Ihres Python-Arbeitsblattcodes¶

Erstellen Sie eine gespeicherte Python-Prozedur über ein Python-Arbeitsblatt, um Ihren Code zu automatisieren. Weitere Informationen zum Schreiben von Python-Arbeitsblättern finden Sie unter Schreiben von Snowpark-Code in Python-Arbeitsblättern.

Beispiel¶

Die Beispiele in diesem Abschnitt veranschaulichen die Rückgabe von Tabellenwerten aus einer Prozedur, die Zeilen herausfiltert, in denen eine Spalte mit einer Zeichenfolge übereinstimmt.

CREATE OR REPLACE TABLE employees(id NUMBER, name VARCHAR, role VARCHAR);
INSERT INTO employees (id, name, role) VALUES (1, 'Alice', 'op'), (2, 'Bob', 'dev'), (3, 'Cindy', 'dev');

CREATE OR REPLACE PROCEDURE filterByRole(tableName VARCHAR, role VARCHAR)
RETURNS TABLE(id NUMBER, name VARCHAR, role VARCHAR)
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'filter_by_role'
AS
$$
from snowflake.snowpark.functions import col

def filter_by_role(session, table_name, role):
   df = session.table(table_name)
   return df.filter(col("role") == role)
$$;

CREATE OR REPLACE PROCEDURE filterByRole(tableName VARCHAR, role VARCHAR)
RETURNS TABLE()
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'filter_by_role'
AS
$$
from snowflake.snowpark.functions import col

def filter_by_role(session, table_name, role):
  df = session.table(table_name)
  return df.filter(col("role") == role)
$$;

CALL filterByRole('employees', 'dev');

+----+-------+------+
| ID | NAME  | ROLE |
+----+-------+------+
| 2  | Bob   | dev  |
| 3  | Cindy | dev  |
+----+-------+------+

Ausführen von gleichzeitigen Aufgaben mit Worker-Prozessen¶

Sie können gleichzeitige Aufgaben mithilfe von Python-Worker-Prozessen ausführen. Dies kann nützlich sein, wenn Sie parallele Aufgaben ausführen müssen, die die Vorteile mehrerer CPU-Kerne auf den Warehouse-Knoten ausnutzen.

Um Fälle zu umgehen, in denen die Python Global Interpreter Lock verhindert, dass ein Multitasking-Ansatz über alle CPU-Kerne skaliert, können Sie gleichzeitige Aufgaben über separate Worker-Prozesse statt über Threads ausführen.

Sie können dies bei Snowflake-Warehouses tun, indem Sie die Klasse Parallel der Bibliothek joblib verwenden, wie in dem folgenden Beispiel.

CREATE OR REPLACE PROCEDURE joblib_multiprocessing_proc(i INT)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.8
  HANDLER = 'joblib_multiprocessing'
  PACKAGES = ('snowflake-snowpark-python', 'joblib')
AS $$
import joblib
from math import sqrt

def joblib_multiprocessing(session, i):
  result = joblib.Parallel(n_jobs=-1)(joblib.delayed(sqrt)(i ** 2) for i in range(10))
  return str(result)
$$;

import joblib
joblib.parallel_backend('loky')