Tabellarische Java-UDFs (UDTFs)¶

Nutzungshinweise für die Partitionierung¶

• Wenn Zeilen empfangen werden, die von Snowflake implizit partitioniert sind, kann Ihr Handler-Code keine Annahmen über Partitionen treffen. Eine Ausführung mit impliziter Partitionierung ist vor allem dann sinnvoll, wenn die UDTF zum Erzeugen der Ausgabe Zeilen nur isoliert betrachten muss und ein Zustand nicht über Zeilen hinweg aggregiert wird. In diesem Fall braucht der Code wahrscheinlich weder einen Konstruktor noch eine endPartition-Methode.

• Zur Verbesserung der Verarbeitungsleistung führt Snowflake normalerweise mehrere Instanzen des Handler-Codes der UDTF parallel aus. Jede Partition von Zeilen wird an eine einzelne Instanz der UDTF übergeben.

• Obwohl jede Partition nur von einer einzigen UDTF-Instanz verarbeitet wird, gilt die Umkehrung nicht: Eine UDTF-Instanz kann mehrere Partitionen nacheinander verarbeiten. Daher ist es wichtig, den Initialisierer und den Finalizer zur Initialisierung und Bereinigung für jede Partition zu verwenden, um zu vermeiden, dass akkumulierte Werte von der Verarbeitung einer Partition zur Verarbeitung einer anderen Partition übertragen werden.

Die Handler-Klasse¶

Snowflake interagiert mit der UDTF in erster Linie über Aufrufe der folgenden Methoden der Handler-Klasse:

• Initialisierer (der Konstruktor)

• Zeilenmethode (process)

• Finalisierungsmethode (endPartition)

Die Handler-Klasse kann zusätzliche Methoden enthalten, die zur Unterstützung dieser drei Methoden erforderlich sind.

Die Handler-Klasse enthält auch eine Methode getOutputClass, die weiter unten beschrieben wird.

Das Auslösen einer Ausnahme durch eine beliebige Methode der Handler-Klasse (oder der Ausgabezeilenklasse) führt zum Abbruch der Verarbeitung. Die Abfrage, mit der die UDTF aufgerufen wurde, schlägt mit einer Fehlermeldung fehl.

import java.util.stream.Stream;

...

public Stream<OutputRow> process(String v) {
  return Stream.of(new OutputRow(v));
}

...

public Stream<OutputRow> process(int number) {
  if (inputNumber < 1) {
    return Stream.empty();
  }
  return Stream.of(new OutputRow(number));
}

Die Ausgabezeilenklasse¶

Snowflake verwendet die Ausgabezeilenklasse, um Konvertierungen zwischen Java-Datentypen und SQL-Datentypen zu spezifizieren.

Wenn eine Java-UDTF eine Zeile zurückgibt, muss der Wert jeder Spalte der Zeile vom Java-Datentyp in den entsprechenden SQL-Datentyp konvertiert werden. Die SQL-Datentypen werden in der RETURNS-Klausel der CREATE FUNCTION-Anweisung angegeben. Die Zuordnung von Java- zu SQL-Datentypen ist jedoch nicht 1:1, sodass Snowflake den Java-Datentyp für jede zurückgegebene Spalte kennen muss. (Weitere Informationen zur Zuordnung von SQL- zu Java-Datentypen finden Sie unter Zuordnung von Datentypen zwischen SQL und Java.)

Eine Java-UDTF spezifiziert die Java-Datentypen der Ausgabespalten durch die Definition einer Ausgabezeilenklasse. Jede von der UDTF zurückgegebene Zeile wird als Instanz der Ausgabezeilenklasse zurückgegeben. Jede Instanz der Ausgabezeilenklasse enthält ein öffentliches Feld für jede Ausgabespalte. Snowflake liest die Werte der öffentlichen Felder aus jeder Instanz der Ausgabezeilenklasse, konvertiert die Java-Werte in SQL-Werte und konstruiert eine SQL-Ausgabezeile, die diese Werte enthält.

Die Werte in jeder Instanz der Ausgabezeilenklasse werden durch den Aufruf des Konstruktors der Ausgabezeilenklasse festgelegt. Der Konstruktor nimmt Parameter entgegen, die den Ausgabespalten entsprechen, und setzt dann die öffentlichen Felder auf diese Parameter.

Der folgende Code definiert ein Beispiel für eine Ausgabezeilenklasse:

class OutputRow {

  public String name;
  public int id;

  public OutputRow(String pName, int pId) {
    this.name = pName;
    this.id = pId
  }

}

Die von dieser Klasse angegebenen öffentlichen Variablen müssen mit den in der RETURNS TABLE (...)-Klausel der CREATE FUNCTION-Anweisung angegebenen Spalten übereinstimmen. Beispielsweise entspricht die obige OutputRow-Klasse der folgenden RETURNS-Klausel:

CREATE FUNCTION F(...)
    RETURNS TABLE(NAME VARCHAR, ID INTEGER)
    ...

Die Ausgabezeilenklasse wird wie folgt verwendet:

• Die Handler-Klasse verwendet die Ausgabezeilenklasse, um den Rückgabetyp der process-Methode und der endPartition-Methode anzugeben. Die Handler-Klasse verwendet auch die Ausgabezeilenklasse, um die zurückgegebenen Werte zu konstruieren. Beispiel:

  public Stream<OutputRow> process(String v) {
    ...
    return Stream.of(new OutputRow(...));
  }
  
  public Stream<OutputRow> endPartition() {
    ...
    return Stream.of(new OutputRow(...));
  }
  

  Copy

• Die Ausgabezeilenklasse wird auch in der getOutputClass-Methode der Handler-Klasse verwendet, die eine statische Methode ist, mit der Snowflake aufgerufen wird, um die Java-Datentypen der Ausgabe zu erfahren:

  public static Class getOutputClass() {
    return OutputRow.class;
  }
  

  Copy

Das Auslösen einer Ausnahme durch eine beliebige Methode der Ausgabezeilenklasse (oder der Handler-Klasse) führt zum Abbruch der Verarbeitung. Die Abfrage, mit der die UDTF aufgerufen wurde, schlägt mit einer Fehlermeldung fehl.

Zusammenfassung der Anforderungen¶

Der Java-Code der UDTFmuss die folgenden Anforderungen erfüllen:

• Der Code muss eine Ausgabezeilenklasse definieren.

• Die Handler-Klasse der UDTF muss eine öffentliche Methode namens process enthalten, die einen „Stream“ der <Ausgabezeilenklasse> zurückgibt, wobei „Stream“ in java.util.stream.Stream definiert ist.

• Die Handler-Klasse der UDTF muss eine öffentliche statische Methode namens getOutputClass definieren, die <Ausgabezeilenklasse>.class zurückgeben muss.

Wenn der Java-Code diese Anforderungen nicht erfüllt, schlägt entweder die Erstellung oder die Ausführung der UDTF fehl:

• Wenn die Sitzung zum Zeitpunkt der Ausführung der CREATE FUNCTION-Anweisung über ein aktives Warehouse verfügt, erkennt Snowflake mögliche Verstöße beim Erstellen der Funktion.

• Wenn die Sitzung zum Zeitpunkt der Ausführung der CREATE FUNCTION-Anweisung kein aktives Warehouse hat, erkennt Snowflake mögliche Verstöße beim Aufrufen der Funktion.

Aufruf ohne explizite Partitionierung¶

Im folgenden Beispiel wird das Erstellen einer UDTF gezeigt: In diesem Beispiel werden zwei Kopien jeder Eingabe zurückgegeben, und für jede Partition wird eine zusätzliche Zeile zurückgegeben.

create function return_two_copies(v varchar)
returns table(output_value varchar)
language java
handler='TestFunction'
target_path='@~/TestFunction.jar'
as
$$

  import java.util.stream.Stream;

  class OutputRow {

    public String output_value;

    public OutputRow(String outputValue) {
      this.output_value = outputValue;
    }

  }


  class TestFunction {

    String myString;

    public TestFunction()  {
      myString = "Created in constructor and output from endPartition()";
    }

    public static Class getOutputClass() {
      return OutputRow.class;
    }

    public Stream<OutputRow> process(String inputValue) {
      // Return two rows with the same value.
      return Stream.of(new OutputRow(inputValue), new OutputRow(inputValue));
    }

    public Stream<OutputRow> endPartition() {
      // Returns the value we initialized in the constructor.
      return Stream.of(new OutputRow(myString));
    }

  }

$$;

Dieses Beispiel zeigt, wie eine UDTF aufgerufen wird. Um dieses Beispiel einfach zu halten, übergibt die Anweisung keine Spalte sondern einen Literalwert und vermeidet die OVER()-Klausel.

SELECT output_value
   FROM TABLE(return_two_copies('Input string'));
+-------------------------------------------------------+
| OUTPUT_VALUE                                          |
|-------------------------------------------------------|
| Input string                                          |
| Input string                                          |
| Created in constructor and output from endPartition() |
+-------------------------------------------------------+

In diesem Beispiel wird die UDTF mit Werten aufgerufen, die aus einer anderen Tabelle gelesen wurden. Jedes Mal, wenn die process-Methode aufgerufen wird, wird ihr ein Wert aus der Spalte city_name der aktuellen Zeile der Tabelle cities_of_interest übergeben. Wie oben wird die UDTF ohne explizite OVER()-Klausel aufgerufen.

Erstellen Sie eine einfache Tabelle, die als Quelle für Eingaben verwendet werden kann:

CREATE TABLE cities_of_interest (city_name VARCHAR);
INSERT INTO cities_of_interest (city_name) VALUES
    ('Toronto'),
    ('Warsaw'),
    ('Kyoto');

Rufen Sie die Java-UDTF auf:

SELECT city_name, output_value
   FROM cities_of_interest,
       TABLE(return_two_copies(city_name))
   ORDER BY city_name, output_value;
+-----------+-------------------------------------------------------+
| CITY_NAME | OUTPUT_VALUE                                          |
|-----------+-------------------------------------------------------|
| Kyoto     | Kyoto                                                 |
| Kyoto     | Kyoto                                                 |
| Toronto   | Toronto                                               |
| Toronto   | Toronto                                               |
| Warsaw    | Warsaw                                                |
| Warsaw    | Warsaw                                                |
| NULL      | Created in constructor and output from endPartition() |
+-----------+-------------------------------------------------------+

Der Beispielabschnitt in der Dokumentation zu JavaScript-UDTFs enthält komplexere Beispiele für Abfragen, die UDTFs mit Werten aus Tabellen aufrufen.

Wenn die Anweisung die Partitionierung nicht explizit angibt, verwendet das Snowflake-Ausführungsmodul die implizite Partitionierung.

Wenn es nur eine einzige Partition gibt, wird die endPartition-Methode nur einmal aufgerufen, und die Ausgabe der Abfrage enthält nur eine Zeile mit dem Wert Created in constructor and output from endPartition(). Wenn die Daten bei verschiedenen Ausführungen der Anweisung in eine unterschiedliche Anzahl von Partitionen gruppiert werden, wird die endPartition-Methode unterschiedlich oft aufgerufen, und die Ausgabe enthält eine unterschiedliche Anzahl von Kopien dieser Zeile.

Weitere Informationen dazu finden Sie unter implizite Partitionierung.

Aufruf mit expliziter Partitionierung¶

Java-UDTFs können auch durch explizite Partitionierung aufgerufen werden.

SELECT city_name, output_value
   FROM cities_of_interest,
       TABLE(return_two_copies(city_name) OVER (PARTITION BY city_name))
   ORDER BY city_name, output_value;
+-----------+-------------------------------------------------------+
| CITY_NAME | OUTPUT_VALUE                                          |
|-----------+-------------------------------------------------------|
| Kyoto     | Created in constructor and output from endPartition() |
| Kyoto     | Kyoto                                                 |
| Kyoto     | Kyoto                                                 |
| Toronto   | Created in constructor and output from endPartition() |
| Toronto   | Toronto                                               |
| Toronto   | Toronto                                               |
| Warsaw    | Created in constructor and output from endPartition() |
| Warsaw    | Warsaw                                                |
| Warsaw    | Warsaw                                                |
+-----------+-------------------------------------------------------+

SELECT city_name, output_value
   FROM cities_of_interest,
       TABLE(return_two_copies(city_name) OVER (PARTITION BY 1))
   ORDER BY city_name, output_value;
+-----------+-------------------------------------------------------+
| CITY_NAME | OUTPUT_VALUE                                          |
|-----------+-------------------------------------------------------|
| Kyoto     | Kyoto                                                 |
| Kyoto     | Kyoto                                                 |
| Toronto   | Toronto                                               |
| Toronto   | Toronto                                               |
| Warsaw    | Warsaw                                                |
| Warsaw    | Warsaw                                                |
| NULL      | Created in constructor and output from endPartition() |
+-----------+-------------------------------------------------------+

Verarbeiten sehr großer Eingaben (z. B. großer Dateien)¶

In einigen Fällen benötigt eine UDTF sehr viel Arbeitsspeicher, um jede Eingabezeile verarbeiten zu können. Eine UDTF könnte zum Beispiel eine Datei lesen und verarbeiten, die zu groß ist, um in den Arbeitsspeicher zu passen.

Um große Dateien in einer UDF oder UDTF zu verarbeiten, verwenden Sie die Klasse SnowflakeFile oder InputStream. Weitere Informationen dazu finden Sie unter Verarbeiten von unstrukturierten Daten mit UDF- und Prozedur-Handlern.