Schreiben von gespeicherten Prozeduren in Snowpark (Python)

Unter diesem Thema wird erklärt, wie Sie eine gespeicherte Prozedur in Python schreiben. Sie können die Snowpark-Bibliothek innerhalb Ihrer gespeicherten Prozedur verwenden, um Abfragen, Aktualisierungen und andere Arbeiten an Tabellen in Snowflake auszuführen.

Unter diesem Thema:

Einführung

Mit gespeicherten Snowpark-Prozeduren können Sie Ihre Datenpipeline in Snowflake erstellen und ausführen, wobei ein Snowflake-Warehouse als Compute-Framework dient. Für den Datenpipeline-Code schreiben Sie gespeicherten Prozeduren unter Verwendung der Snowpark-API für Python. Um die Ausführung dieser gespeicherten Prozeduren zu planen, verwenden Sie Aufgaben (Tasks).

Weiter Informationen zu Machine Learning-Modellen und zu Snowpark Python finden Sie unter Training von Machine Learning-Modellen mit Snowpark Python.

Die nächsten Abschnitte enthalten weitere Informationen zu gespeicherten Snowpark-Prozeduren für Python.

Bemerkung

Um eine anonyme Prozedur sowohl zu erstellen als auch aufzurufen, verwenden Sie CALL (mit anonymen Prozeduren). Das Erstellen und Aufrufen einer anonymen Prozedur erfordert keine Rolle mit CREATE PROCEDURE-Schemaberechtigungen.

Voraussetzungen

Sie müssen Version 0.4.0 oder eine neuere Version der Snowpark-Bibliothek verwenden.

Snowflake unterstützt derzeit das Schreiben von gespeicherten Prozeduren in der Python-Version 3.8.

Bemerkung

Gespeicherte Python-Prozeduren erfordern die neueste Snowpark Python-Bibliothek, wodurch zusätzliche Abhängigkeiten von Drittanbietern eingeführt werden. Bevor Sie mit dem Erstellen einer gespeicherten Python-Prozedur beginnen, vergewissern Sie sich erst, ob das Anaconda Packages-Feature aktiviert ist, damit die erforderlichen Abhängigkeiten von Drittanbietern auch geladen werden können. Weitere Informationen dazu finden Sie unter Verwenden von Drittanbieterpaketen aus Anaconda.

Einrichten Ihrer Entwicklungsumgebung für Snowpark

Stellen Sie sicher, dass Ihre Entwicklungsumgebung für die Verwendung der Snowpark-Bibliothek eingerichtet ist. Weitere Informationen dazu finden Sie unter Einrichten Ihrer Entwicklungsumgebung für Snowpark

Auswahl zwischen Erstellen einer gespeicherten Prozedur mit Inline-Code oder durch Hochladen des Codes aus einem Stagingbereich

Wie bei Python-UDFs können Sie entweder eine inline gespeicherte Prozedur erstellen oder eine gespeicherte Prozedur, deren Code aus einem Stagingbereich hochgeladen wird.

  • Bei einer inline gespeicherten Prozedur schreiben Sie den Python-Code in die AS-Klausel der CREATE PROCEDURE-Anweisung. Beispiel:

    CREATE OR REPLACE PROCEDURE MYPROC(from_table STRING, to_table STRING, count INT)
      RETURNS STRING
      LANGUAGE PYTHON
      RUNTIME_VERSION = '3.8'
      PACKAGES = ('snowflake-snowpark-python')
      HANDLER = 'run'
    AS
    $$
    def run(session, from_table, to_table, count):
      session.table(from_table).limit(count).write.save_as_table(to_table)
      return "SUCCESS"
    $$;
    
  • Bei einer gespeicherten Prozedur, die mit Code erstellt wurde, der aus einem Stagingbereich hochgeladen wurde, schreiben Sie Ihren Python-Code in eine .py-Quelldatei. Sie können zum Beispiel den folgenden Code in eine Datei namens my_py_file.py schreiben:

    def run(session, from_table, to_table, count):
      session.table(from_table).limit(count).write.save_as_table(to_table)
      return "SUCCESS"
    

    Anschließend laden Sie die Datei in einen Stagingbereich und führen den CREATE PROCEDURE-Befehl aus, wobei Sie auf die Datei im Stagingbereich verweisen. Beispiel:

    CREATE OR REPLACE PROCEDURE MYPROC(from_table STRING, to_table STRING, count INT)
      RETURNS INT
      LANGUAGE PYTHON
      RUNTIME_VERSION = '3.8'
      PACKAGES = ('snowflake-snowpark-python')
      IMPORTS = ('@mystage/my_py_file.py')
      HANDLER = 'my_py_file.run';
    

Schreiben des Python-Codes für die gespeicherte Prozedur

Für den Code Ihrer gespeicherten Prozedur müssen Sie eine Python-Methode oder -Funktion schreiben.

Planen des Schreibens Ihrer gespeicherten Prozedur

Wie unten beschrieben unterliegt der für Ihre gespeicherte Prozedur geschriebene Python-Code denselben Einschränkungen wie der Code einer Python-UDF. Bei der Planung Ihrer gespeicherten Prozeduren sollten Sie diese Einschränkungen berücksichtigen.

Belegung des Arbeitsspeichers begrenzen

Wie bei Python-UDFs belegt Snowflake Methoden oder Funktionen mit einer Begrenzung hinsichtlich der benötigten Menge an Arbeitsspeicher.

In Ihrer Methode oder Funktion sollten Sie darauf achten, nicht zu viel Arbeitsspeicher zu verbrauchen.

Thread-sicheren Code schreiben

Ähnlich wie bei Python-UDFs müssen Sie sicherstellen, dass Ihre Methode oder Funktion threadsicher ist.

Erläuterungen zu Sicherheitseinschränkungen

Ihre Methode oder Funktion wird innerhalb einer eingeschränkten Engine ausgeführt. Daher müssen Sie die gleichen Regeln befolgen, wie sie für Python-UDFs dokumentiert sind.

Entscheiden Sie, ob Sie die Eigentümerrechte oder die Aufruferrechte nutzen möchten.

Außerdem müssen Sie bei der Planung Ihrer gespeicherten Prozedur berücksichtigen, ob Sie die gespeicherte Prozedur mit Aufruferrechten oder Eigentümerrechten ausführen möchten.

„snowflake-snowpark-python“-Version beachten

Die „snowflake-snowpark-python“-Bibliothek, die in der Umgebung für die gespeicherte Python-Prozedur verfügbar ist, liegt normalerweise eine Version hinter der öffentlich freigegebenen Version zurück. Dies ist auf die Einschränkungen des Freigabeprozesses für gespeicherte Prozeduren zurückzuführen. Benutzen Sie folgende SQL, um die neueste verfügbare „snowflake-snowpark-python“-Version zu ermitteln.

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

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.

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 Zugriff auf und Einstellung des Sitzungsstatus.

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.

Es folgt ein Beispiel für eine Python-Methode, die eine bestimmte Anzahl von Zeilen aus einer Tabelle in eine andere Tabelle kopiert. Der Methode werden die folgenden Argumente übergeben:

  • Ein Snowpark-Session-Objekt

  • Der Name der Tabelle, aus der die Zeilen kopiert werden sollen

  • Der Name der Tabelle, in der die Zeilen gespeichert werden sollen

  • Die Anzahl der zu kopierenden Zeilen

Die Methode in diesem Beispiel gibt eine Zeichenfolge zurück.

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

session.table(from_table).limit(count).write.save_as_table(to_table)
  return "SUCCESS"

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, indem Sie die folgenden Schritte ausführen.

Bemerkung

  • Um die Schritte in diesem Abschnitt ausführen zu können, ist die Rolle des Organisationsadministrators (ORGADMIN) erforderlich. Informationen zu Organisationen finden Sie unter Verwalten Ihrer Snowflake-Organisation.

  • Um die Bedingungen zu akzeptieren, müssen für den Benutzer die folgenden Benutzereigenschaften eingestellt sein:

    • Vorname

    • Nachname

    • E-Mail-Adresse


    Wenn die Benutzereigenschaften nicht festgelegt sind, zeigt die Snowflake-UI eine Meldung an, die Sie auffordert, diese Eigenschaften zu aktualisieren, bevor Sie fortfahren. Ein Benutzeradministrator (d. h. ein Benutzer mit der Rolle USERADMIN) oder eine höhere Rolle oder eine andere Rolle mit OWNERSHIP-Berechtigung für Ihr Snowflake-Benutzerobjekt kann diese Details zu Ihrem Benutzerprofil hinzufügen.

  1. Melden Sie sich bei Snowsight, der Snowflake-Weboberfläche, an.

  2. Klicken Sie auf das Dropdown-Menü neben Ihrem Anmeldenamen, und klicken Sie dann auf Switch Role » ORGADMIN, um zur Rolle des Organisationsadministrators zu wechseln.

  3. Klicken Sie auf Admin » Billing » Terms & Billing.

  4. Scrollen Sie zum Abschnitt Anaconda, und klicken Sie auf die Schaltfläche Enable. Das Dialogfenster Anaconda Packages (Preview Feature) wird geöffnet.

  5. Klicken Sie auf den Link, um die Snowflake-Bedingungen für Drittanbieter zu prüfen.

  6. Wenn Sie mit den Bedingungen einverstanden sind, klicken Sie auf die Schaltfläche Acknowledge & Continue.

Bemerkung

Wenn Sie die Snowflake-Bedingungen für Drittanbieter wie oben beschrieben nicht anerkennen, können Sie dennoch gespeicherte Prozeduren verwenden, allerdings mit folgenden Einschränkungen:

  • Sie können keine Pakete von Drittanbietern aus Anaconda verwenden.

  • Sie können Snowpark Python weiterhin als Paket in einer gespeicherten Prozedur angeben, aber Sie können keine bestimmte Version angeben.

  • Sie können die to_pandas-Methode nicht zum Interagieren mit einem DataFrame-Objekt verwenden.

Anzeigen und Verwenden von Paketen

Sie können alle verfügbaren Pakete und deren Versionsinformationen anzeigen, indem Sie die Ansicht PACKAGES des Information Schema 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.

Zugriff auf andere Klassen und Ressourcendateien

Wenn Ihr Code von anderen Ressourcendateien oder Python-Modulen abhängt, die außerhalb der gespeicherten Prozedur definiert sind, müssen Sie diese Dateien in einen Stagingbereich hochladen, damit die Dateien bei Ausführung der gespeicherten Prozedur verfügbar sind.

Bei der späteren Ausführung der CREATE PROCEDURE-Anweisung verwenden Sie die IMPORTS-Klausel, um auf diese Dateien zu verweisen.

Hochladen von Dateien in einen Stagingbereich

Hochladen der für Ihre gespeicherte Prozedur erforderlichen Dateien in einen Stagingbereich:

  1. Wählen Sie den Stagingbereich für Ihre Dateien aus.

    Sie können einen externen oder einen benannten internen Stagingbereich verwenden. Wenn Sie die Dateien mit dem Befehl PUT hochladen möchten, verwenden Sie einen benannten internen Stagingbereich. (Mit dem PUT-Befehl können keine Dateien in externe Stagingbereiche hochgeladen werden.)

    Sie können einen vorhandenen Stagingbereich verwenden oder einen neuen Stagingbereich erstellen, indem Sie CREATE STAGE ausführen. Der folgende Befehl erstellt beispielsweise einen neuen internen Stagingbereich namens mystage:

    CREATE STAGE mystage;
    

    Bemerkung

    Der Eigentümer der gespeicherten Prozedur muss die READ-Berechtigung für den Stagingbereich haben.

  2. Verwenden Sie den Befehl PUT, um die folgenden Dateien in diesen Stagingbereich hochzuladen:

    • Die Datei, die Ihren Python-Code enthält.

    • Alle anderen Dateien, von denen Ihre gespeicherte Prozedur abhängt.

    Beispiel:

    put file:///users/myusername/myfile.py
            @mystage
            AUTO_COMPRESS = FALSE
            OVERWRITE = TRUE
            ;
    

    Bemerkung

    Wenn Sie AUTO_COMPRESS = FALSE weglassen, komprimiert der PUT-Befehl die Datei automatisch. Der Name der komprimierten Datei im Stagingbereich wird myfile.py.gz sein. Wenn Sie später den Befehl CREATE PROCEDURE ausführen, müssen Sie den Dateinamen in der IMPORTS-Klausel mit dieser .gz-Erweiterung angeben.

    Bemerkung

    Mit dem PUT-Befehl können keine Dateien in externe Stagingbereiche hochgeladen werden. Verwenden Sie die vom Clouddienst bereitgestellten Dienstprogramme, um Dateien in externe Stagingbereiche hochzuladen.

Beachten Sie, dass Sie die gespeicherte Prozedur nicht mehr aufrufen können, wenn Sie die Datei, die Ihren Python-Code enthält, löschen oder umbenennen.

Wenn Sie die Datei aktualisieren müssen, gehen Sie wie folgt vor:

  • Aktualisieren Sie die Datei, wenn keine Aufrufe an die gespeicherte Prozedur erfolgen können.

  • Fügen Sie die Klausel OVERWRITE=TRUE zum Befehl PUT hinzu.

Erstellen der gespeicherten Prozedur

Führen Sie die CREATE PROCEDURE-Anweisung aus, um eine gespeicherte Prozedur für Ihre Methode oder Funktion zu erstellen.

Bemerkung

Um eine anonyme Prozedur sowohl zu erstellen als auch aufzurufen, verwenden Sie CALL (mit anonymen Prozeduren). Das Erstellen und Aufrufen einer anonymen Prozedur erfordert keine Rolle mit CREATE PROCEDURE-Schemaberechtigungen.

Legen Sie die in der nachfolgenden Tabelle aufgeführten CREATE PROCEDURE-Parameter fest.

Parameter

Beschreibung

[ arg_name arg_data_type [, ... ] ]

  • Lassen Sie das Argument für das Snowpark-Session-Objekt weg. Wie bereits erwähnt, handelt es sich hierbei nicht um einen formalen Parameter, den Sie in CREATE PROCEDURE oder CALL angeben. Wenn Sie Ihre gespeicherte Prozedur aufrufen, erstellt Snowflake ein Session-Objekt und übergibt dieses an Ihre gespeicherte Prozedur.

  • Verwenden Sie als Datentypen der übrigen Argumente die Snowflake-Datentypen, die den Python-Typen der Argumente in Ihrer Methode oder Funktion entsprechen.

RETURNS result_data_type

Geben Sie für RETURNS den Snowflake-Datentyp Ihres Rückgabewerts an.

LANGUAGE PYTHON

Dies müssen Sie angeben, um anzuzeigen, dass Ihr gespeicherter Prozedurcode in Python geschrieben ist.

RUNTIME_VERSION = '3.8'

Dies müssen Sie angeben, um anzuzeigen, dass Ihre gespeicherte Prozedur Python 3.8 verwendet.

PACKAGES = ( 'package_name' )

Nehmen Sie in diese Liste das Paket für die Version der Snowpark-Bibliothek auf, die Sie verwenden möchten.

Geben Sie den vollqualifizierten Paketnamen der Snowpark-Bibliothek in folgendem Format an:

snowflake-snowpark-python==<version>

Beispiel:

  • Für die neueste Version von Snowpark verwenden Sie:

    PACKAGES = ('snowflake-snowpark-python')
    
  • Für die Version 0.4.0 von Snowpark verwenden Sie:

    PACKAGES = ('snowflake-snowpark-python==0.4.0')
    

IMPORTS = ( 'file' [, 'file' ... ] )

Wenn Sie eine inline gespeicherte Prozedur schreiben, können Sie diese Klausel weglassen, es sei denn, Ihr Code hängt von Klassen ab, die außerhalb der gespeicherten Prozedur oder der Ressourcendateien definiert sind.

Wenn Sie eine gespeicherte Prozedur erstellen, indem Sie Code aus einem Stagingbereich hochladen, nehmen Sie diese Datei in diese Liste mit auf.

Wenn Ihre gespeicherte Prozedur von Dateien abhängt, die Sie in einen Stagingbereich hochgeladen haben, nehmen Sie diese Dateien in die Liste auf.

HANDLER = 'method_name'

Verwenden Sie hier den vollqualifizierten Namen Ihrer Python-Methode oder -Funktion.

EXECUTE AS CALLER

Wenn Sie geplant haben, die gespeicherte Prozedur so einzurichten, dass sie Aufruferrechte verwendet, fügen Sie diesen Parameter hinzu.

Wenn Sie dagegen Eigentümerrechte verwenden möchten, lassen Sie diesen Parameter einfach weg.

In den folgenden Beispielen werden gespeicherte Prozeduren in Python erstellt.

Beispiel 1: Inline gespeicherte Prozedur

CREATE OR REPLACE PROCEDURE myProc(from_table STRING, to_table STRING, count INT)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'run'
AS
$$
def run(session, from_table, to_table, count):
  session.table(from_table).limit(count).write.save_as_table(to_table)
  return "SUCCESS"
$$;

Beispiel 2: Eine gespeicherte Prozedur, die Code verwendet, der aus einem Stagingbereich in die Python-Datei myfile.py im internen Stagingbereich mystage hochgeladen wurde:

CREATE OR REPLACE PROCEDURE myProc(from_table STRING, to_table STRING, count INT)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
IMPORTS = ('@mystage/myfile.py')
HANDLER = 'myfile.run'

Aufrufen Ihrer gespeicherten Prozedur

Damit ein Benutzer eine gespeicherte Prozedur aufrufen kann, muss die Rolle des Benutzers die USAGE-Berechtigung für diese gespeicherte Prozedur haben.

Sobald Sie die Berechtigung zum Aufrufen der gespeicherten Prozedur haben, können Sie mit der CALL-Anweisung die gespeicherte Prozedur aufrufen. Beispiel:

CALL myProc('table_a', 'table_b', 5);

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.

  • Wenn Sie Ihre gespeicherte Prozedur von einer Aufgabe aus ausführen, müssen Sie beim Erstellen der Aufgabe ein Warehouse angeben. (Sie können für die Ausführung der Aufgabe keine von Snowflake verwalteten Computeressourcen verwenden).

  • 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 mit session.file.get aus dem Stagingbereich wird die Mustererkennung nicht unterstützt.

  • Bei Verwendung von joblib.Parallel in einer Python-UDF oder einer gespeicherten Prozedur muss der Parameter backend auf threading gesetzt werden. Weitere Informationen dazu finden Sie in der Dokumentation zur Verwendung von Drittanbieterpaketen.

Zurück zum Anfang