Java-Handler für mit SQL erstellten gespeicherte Prozeduren schreiben¶

Schreiben eines Java-Handlers für eine gespeicherte Prozedur¶

1. Stellen Sie sicher, dass Ihre Umgebung die Voraussetzungen von erfüllt.

2. Wenn Sie lokal entwickeln, richten Sie Ihre Umgebung so ein, dass Sie Snowpark verwenden.

3. Wählen Sie, ob Sie Ihren Handler inline oder in einem Stagingbereich einsetzen möchten.

4. Befolgen Sie die Richtlinien für die Klasse, Methode und Leistung des Handlers.

5. Implementieren Sie Unterstützung für Features wie Datenzugriff, Lesen von Dateien, Rückgabe von Tabellendaten und Protokollierung und Ablaufverfolgung.

6. Machen Sie die Abhängigkeiten Ihres Codes auf Snowflake verfügbar.

7. Fügen Sie Ihren Handler-Code inline oder importiert aus einem Stagingbereich ein, wenn Sie die gespeicherte Prozedur erstellen.

Voraussetzungen¶

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

Wenn Sie eine gespeicherte Prozedur schreiben, müssen Sie Ihre Klassen für die Ausführung in folgenden Java-Versionen kompilieren:

• 11.x

• 17.x

Einrichten Ihrer Entwicklungsumgebung für Snowpark¶

Wenn Sie Ihren Code lokal entwickeln, richten Sie Ihre Entwicklungsumgebung für die Verwendung der Snowpark-Bibliothek ein. Siehe Einrichten Ihrer Entwicklungsumgebung für Snowpark Java.

Strukturieren und Erstellen von Handler-Code¶

Sie können den Handler-Quellcode inline mit demSQL-Code aufbewahren, der die Prozedur erstellt, oder das kompilierte Ergebnis des Handlers an einem separaten Ort aufbewahren und von SQL aus referenzieren. Weitere Informationen dazu finden Sie unter Speichern von Handler-Code inline oder in einem Stagingbereich.

Weitere Informationen zum Erstellen von Handler-Quellcode zur Verwendung mit einer Prozedur finden Sie unter Packen des Handler-Codes.

Richtlinien für die Handler-Klasse¶

Beim Schreiben der Klasse ist Folgendes zu beachten:

• Die Klasse und die Methode dürfen nicht geschützt oder privat sein.

• Wenn die Methode nicht statisch ist und Sie einen Konstruktor definieren möchten, definieren Sie einen Null-Argument-Konstruktor für die Klasse. Snowflake ruft diesen Null-Argument-Konstruktor zur Initialisierungszeit auf, um eine Instanz Ihrer Klasse zu erstellen.

• Sie können in derselben Klasse verschiedene Methoden für verschiedene gespeicherte Prozeduren definieren.

Richtlinien für die Handler-Methode¶

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

• Geben Sie das Snowpark-Session-Objekt als erstes Argument Ihrer Methode 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 den Rückgabewert werden die Java-Typen verwendet, die den Snowflake-Datentypen entsprechen.

• Ihre Methode muss einen Wert zurückgeben. Für gespeicherte Prozeduren in Java ist ein Rückgabewert erforderlich.

• Die Ausführung einer gespeicherten Prozedur wird zeitlich begrenzt, es sei denn, der Timer wird durch die Aktivität des Codes zurückgesetzt. Insbesondere wird der Timeout-Timer durch die Interaktionen des Codes mit Daten zurückgesetzt, einschließlich Dateioperationen, Abfragen und Iterationen durch ein Resultset.

• Wenn Sie einen asynchronen untergeordneten Job aus dem Handler einer Prozedur heraus ausführen, wird „Fire-and-Forget“ nicht unterstützt.

  Mit anderen Worten: Wenn der Handler eine untergeordnete Abfrage ausgibt, die noch ausgeführt wird, wenn der Job der übergeordneten Prozedur abgeschlossen ist, wird der untergeordnete Job automatisch abgebrochen.

Fehlerbehandlung¶

Sie können die üblichen Java-Techniken zur Ausnahmebehandlung verwenden, um Fehler innerhalb des Handler-Codes 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.

Richtlinien für die Leistung und Sicherheit von Handlern¶

Um sicherzustellen, dass Ihr Code unter Snowflake gut läuft, befolgen Sie folgende Richtlinien:

• Begrenzen Sie den Verbrauch von Arbeitsspeicher.

  Snowflake belegt Methoden mit einer Begrenzung hinsichtlich der benötigten Menge an Arbeitsspeicher. Weitere Informationen dazu, wie Sie zu hohen Speicherverbrauch vermeiden können, finden Sie unter Entwerfen von Handlern unter Berücksichtigung der Snowflake-bedingten Einschränkungen.

• Schreiben Sie thread-sicheren Code.

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

• Beachten Sie die Sicherheitseinschränkungen.

  Da Ihr Handler-Code wird innerhalb einer eingeschränkten Engine ausgeführt wird, sollten Sie unbedingt die unter Sicherheitsverfahren für UDFs und Prozeduren beschriebenen Regeln befolgen.

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

  Entscheiden Sie bei der Planung Ihrer gespeicherten Prozedur, ob Sie die gespeicherte Prozedur mit Aufruferrechten oder Eigentümerrechten ausführen möchten.

• Berücksichtigen Sie das Timeout-Verhalten von gespeicherten Prozeduren.

  Die Ausführung einer gespeicherten Prozedur wird zeitlich begrenzt, es sei denn, der Timer wird durch die Aktivität des Codes zurückgesetzt. Insbesondere wird der Timeout-Timer durch die Interaktionen des Codes mit Daten zurückgesetzt, einschließlich Dateioperationen, Abfragen und Iterationen durch ein Resultset.

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. Klassen in einer JAR-Datei) oder von Ressourcendateien, können Sie diese Abhängigkeiten für Ihren Code zur Verfügung stellen, indem Sie ihn in einen Stagingbereich hochladen. Beim Erstellen der Prozedur können Sie diese Abhängigkeiten mithilfe der IMPORTS-Klausel referenzieren.

Weitere Informationen dazu finden Sie unter Abhängigkeiten für Code zur Verfügung stellen.