Schreiben von gespeicherten Prozeduren in Scala¶

Voraussetzungen¶

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

Wenn Sie eine gespeicherte Prozedur schreiben, deren Handler-Code in einen Stagingbereich kopiert wird, müssen Sie Ihre Klassen für die Ausführung in Java, Version 11.x kompilieren.

Einrichten Ihrer Entwicklungsumgebung für Snowpark¶

Richten Sie Ihre Entwicklungsumgebung für die Verwendung der Snowpark-Bibliothek ein. Siehe Einrichten Ihrer Entwicklungsumgebung für Snowpark Scala.

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.

Einschränkungen¶

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

• Parallelität wird nicht unterstützt. So können Sie beispielsweise über Ihren Code keine Abfragen von mehreren Threads übermitteln. Code, der mehrere Abfragen gleichzeitig ausführt, führt zu einem Fehler.

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

• Das Lesen und Schreiben von Dateien aus in Scala geschriebenem Handler-Code von gespeicherten Prozeduren wird noch nicht vollständig unterstützt. Das Lesen und Schreiben von Dateien kann zu instabilem Verhalten führen. Dazu zählt das Empfangen eines InputStream als Argument und die Verwendung von Methoden, die in der Klasse FileOperation verfügbar sind (auf die Sie normalerweise über die Methode Session.file zugreifen), einschließlich put und get.

• Beachten Sie die folgenden Einschränkungen für die Verwendung von Snowpark-APIs in Ihrer gespeicherten Prozedur.

  • Wenn Sie APIs verwenden, die PUT- und GET-Befehle ausführen (einschließlich Session.sql("PUT ...") und Session.sql("GET ...")), dürfen Sie nur in das Verzeichnis „/tmp“ des speichergestützten Dateisystems schreiben, das für die Abfrage vorgesehen ist, das die Prozedur aufruft.

  • Verwenden Sie keine APIs für asynchrone Aktionen.

  • Verwenden Sie keine APIs, die neue Sitzungen erstellen (z. B. Session.builder().configs(...).create()).

  • Die Verwendung von session.jdbcConnection (und der zurückgegebenen Verbindung) wird nicht unterstützt, da dies zu unsicherem Verhalten führen kann.

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

Schreiben der Klasse oder des Objekts¶

Die Methode oder Funktion, die Sie definieren, muss Teil einer Klasse oder eines Objekts sein.

Beim Schreiben der Klasse oder des Objekts ist Folgendes zu beachten:

• Die Klasse (oder das Objekt) 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 oder demselben Objekt verschiedene Methoden für verschiedene gespeicherte Prozeduren definieren.

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 den Rückgabewert werden die Scala-Typen verwendet, die den Snowflake-Datentypen entsprechen.

• Ihre Methode oder Funktion muss einen Wert zurückgeben. Für gespeicherte Prozeduren in Scala 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.

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.

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 Scala-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 für Scala.

object MyObject
{
  def myProcedure(session: com.snowflake.snowpark.Session, fromTable: String, toTable: String, count: Int): String =
  {
    session.table(fromTable).limit(count).write.saveAsTable(toTable)
    return "Success"
  }
}

object MyObject
{
  val myProcedure = (session: com.snowflake.snowpark.Session, fromTable: String, toTable: String, count: Int): String =>
  {
    session.table(fromTable).limit(count).write.saveAsTable(toTable)
    "Success"
  }
}

Zugriff auf andere Klassen und Ressourcendateien¶

Wenn Ihr Code von Klassen abhängt, die außerhalb der gespeicherten Prozedur definiert sind (z. B. Klassen in einer separaten JAR-Datei), oder von Ressourcendateien, können Sie diese Abhängigkeiten dem Handler zur Verfügung stellen, indem Sie die Dateien in einen Stagingbereich hochladen. Weitere Informationen dazu finden Sie unter Abhängigkeiten für Code zur Verfügung stellen.

Wenn Sie später die CREATE PROCEDURE-Anweisung ausführen, verwenden Sie die IMPORTS-Klausel, um auf diese Dateien zu verweisen.

Kompilieren und Packen Ihres Scala-Codes¶

Um das Einrichten Ihrer gespeicherten Prozedur zu vereinfachen, erstellen Sie eine JAR-Datei, die alle für Ihre gespeicherte Prozedur benötigten Abhängigkeiten enthält. Später müssen Sie die JAR-Datei in einen Stagingbereich hochladen und in Ihrer CREATE PROCEDURE-Anweisung auf die JAR-Datei verweisen. Dieser Vorgang ist einfacher, wenn Sie weniger JAR-Dateien hochladen und auf sie verweisen müssen.

Hochladen von Dateien in einen Stagingbereich¶

Um die Logik Ihrer Prozedur (und ggf. andere Abhängigkeiten) für die Prozedur zur Verfügung zu stellen, müssen Sie die erforderlichen Dateien in einen Stagingbereich hochladen. Weitere Informationen dazu finden Sie unter Abhängigkeiten für Code zur Verfügung stellen.

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 filter_by_role(table_name VARCHAR, role VARCHAR)
RETURNS TABLE(id NUMBER, name VARCHAR, role VARCHAR)
LANGUAGE SCALA
RUNTIME_VERSION = '2.12'
PACKAGES = ('com.snowflake:snowpark:latest')
HANDLER = 'Filter.filterByRole'
AS
$$
import com.snowflake.snowpark.functions._
import com.snowflake.snowpark._

object Filter {
    def filterByRole(session: Session, tableName: String, role: String): DataFrame = {
        val table = session.table(tableName)
        val filteredRows = table.filter(col("role") === role)
        return filteredRows
    }
}
$$;

CREATE OR REPLACE PROCEDURE test_return_geography_table_1()
RETURNS TABLE(g GEOGRAPHY)
...

CALL test_return_geography_table_1();

Stored procedure execution error: data type of returned table does not match expected returned table type

CREATE OR REPLACE PROCEDURE test_return_geography_table_1()
RETURNS TABLE()
...

CREATE OR REPLACE PROCEDURE filter_by_role(table_name VARCHAR, role VARCHAR)
RETURNS TABLE()
LANGUAGE SCALA
RUNTIME_VERSION = '2.12'
PACKAGES = ('com.snowflake:snowpark:latest')
HANDLER = 'Filter.filterByRole'
AS
$$
import com.snowflake.snowpark.functions._
import com.snowflake.snowpark._

object Filter {
    def filterByRole(session: Session, tableName: String, role: String): DataFrame = {
        val table = session.table(tableName)
        val filteredRows = table.filter(col("role") === role)
        return filteredRows
    }
}
$$;

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

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