Beispiele für Java-UDF-Handler¶

Übergeben von NULL an eine Inline-Java-UDF¶

Hier wird die oben definierte echo_varchar()-UDF verwendet. Der SQL NULL-Wert wird implizit in einen Java null-Wert umgewandelt, und dieser Java null-Wert wird zurückgegeben und implizit wieder in SQL-NULL umgewandelt:

Aufrufen der UDF:

SELECT echo_varchar(NULL);
+--------------------+
| ECHO_VARCHAR(NULL) |
|--------------------|
| NULL               |
+--------------------+

Werteübergabe via ARRAY¶

Deklarieren Sie den Java-Parameter als Array. In der folgenden Methode ist dritte Parameter beispielsweise ein String-Array:

static int myMethod(int fixedArgument1, int fixedArgument2, String[] stringArray)

Copy

Nachfolgend finden Sie ein vollständiges Beispiel:

Erstellen und Laden der Tabelle:

CREATE TABLE string_array_table(id INTEGER, a ARRAY);
INSERT INTO string_array_table (id, a) SELECT
        1, ARRAY_CONSTRUCT('Hello');
INSERT INTO string_array_table (id, a) SELECT
        2, ARRAY_CONSTRUCT('Hello', 'Jay');
INSERT INTO string_array_table (id, a) SELECT
        3, ARRAY_CONSTRUCT('Hello', 'Jay', 'Smith');

Copy

Erstellen der UDF:

create or replace function concat_varchar_2(a ARRAY)
returns varchar
language java
handler='TestFunc_2.concatVarchar2'
target_path='@~/TestFunc_2.jar'
as
$$
    class TestFunc_2 {
        public static String concatVarchar2(String[] strings) {
            return String.join(" ", strings);
        }
    }
$$;

Copy

Aufrufen der UDF:

SELECT concat_varchar_2(a)
    FROM string_array_table
    ORDER BY id;
+---------------------+
| CONCAT_VARCHAR_2(A) |
|---------------------|
| Hello               |
| Hello Jay           |
| Hello Jay Smith     |
+---------------------+

Copy

Werteübergabe via varargs¶

Die Verwendung von varargs ist der Verwendung eines Arrays sehr ähnlich.

Verwenden Sie in Ihrem Java-Code den varargs-Deklarationsstil von Java:

static int myMethod(int fixedArgument1, int fixedArgument2, String ... stringArray)

Copy

Nachfolgend finden Sie ein vollständiges Beispiel. Der einzige wesentliche Unterschied zwischen diesem Beispiel und dem vorangegangenen Beispiel (für Arrays) ist die Deklaration der Parameter für die Methode.

Erstellen und Laden der Tabelle:

CREATE TABLE string_array_table(id INTEGER, a ARRAY);
INSERT INTO string_array_table (id, a) SELECT
        1, ARRAY_CONSTRUCT('Hello');
INSERT INTO string_array_table (id, a) SELECT
        2, ARRAY_CONSTRUCT('Hello', 'Jay');
INSERT INTO string_array_table (id, a) SELECT
        3, ARRAY_CONSTRUCT('Hello', 'Jay', 'Smith');

Copy

Erstellen der UDF:

create or replace function concat_varchar(a ARRAY)
returns varchar
language java
handler='TestFunc.concatVarchar'
target_path='@~/TestFunc.jar'
as
$$
    class TestFunc {
        public static String concatVarchar(String ... stringArray) {
            return String.join(" ", stringArray);
        }
    }
$$;

Copy

Aufrufen der UDF:

SELECT concat_varchar(a)
    FROM string_array_table
    ORDER BY id;
+-------------------+
| CONCAT_VARCHAR(A) |
|-------------------|
| Hello             |
| Hello Jay         |
| Hello Jay Smith   |
+-------------------+

Copy

Voraussetzungen¶

Bevor der Java-Handler-Code eine in einem Stagingbereich befindliche Datei lesen kann, müssen Sie Folgendes tun, um die Datei für den Code zur Verfügung zu stellen:

1. Erstellen Sie einen Stagingbereich, auf den Ihr Handler zugreifen kann.

   Sie können einen externen Stagingbereich oder eine interne Stagingbereich verwenden. Wenn Sie einen internen Stagingbereich verwenden, muss es sich um einen Benutzer- oder benannten Stagingbereich handeln. Snowflake unterstützt derzeit nicht die Verwendung von Tabellen-Stagingbereichen für UDF-Abhängigkeiten. Weitere Informationen zum Erstellen eines Stagingbereichs finden Sie unter CREATE STAGE. Weitere Informationen zur Auswahl des Typs eines internen Stagingbereichs finden Sie unter Auswahl eines internen Stagingbereichs für lokale Dateien.

   Denken Sie daran, dass Rollen, die SQL-Aktionen zum Lesen aus einem Stagingbereich ausführen, entsprechende Berechtigungen für den jeweiligen Stagingbereich zugewiesen sein müssen. Weitere Informationen dazu finden Sie unter Granting Privileges for User-Defined Functions.

2. Kopieren Sie die Datei, die vom Code gelesen werden soll, in den Stagingbereich.

   Sie können die Datei von einem lokalen Laufwerk in einen Stagingbereich kopieren, indem Sie den Befehl PUT verwenden. Weitere Informationen zu diesem Befehl finden Sie unter PUT. Weitere Informationen zum Staging von Dateien mit PUT finden Sie unter Staging von Datendateien aus einem lokalen Dateisystem.

Lesen einer in IMPORTS statisch spezifizierten Datei¶

Ihr Handler kann eine Datei lesen, deren Stagingbereich in der IMPORTS-Klausel des Befehls CREATE FUNCTION angegeben wurde.

Wenn in der IMPORTS-Klausel eine Datei angegeben wird, kopiert Snowflake diese Datei vom Stagingbereich in das Basisverzeichnis der UDF (auch Home-Verzeichnis oder Importverzeichnis genannt), welches das Verzeichnis ist, aus dem die UDF die Datei schließlich ausliest.

Da importierte Dateien in ein einziges Verzeichnis kopiert werden und innerhalb dieses Verzeichnisses eindeutige Namen haben müssen, muss jede Datei in der IMPORTS-Klausel einen eindeutigen Namen haben, auch wenn sich die Dateien in verschiedenen Stagingbereichen oder verschiedenen Unterverzeichnissen innerhalb eines Stagingbereichs befinden.

Im folgenden Beispiel wird eine Java-UDF zum Lesen einer Datei erstellt und aufgerufen.

Der Java-Quellcode erstellt eine Java-Methode mit dem Namen readFile. Die UDF verwendet diese Methode.

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.stream.Stream;

class TestReadRelativeFile {
    public static String readFile(String fileName) throws IOException {
        StringBuilder contentBuilder = new StringBuilder();
        String importDirectory = System.getProperty("com.snowflake.import_directory");
        String fPath = importDirectory + fileName;
        Stream<String> stream = Files.lines(Paths.get(fPath), StandardCharsets.UTF_8);
        stream.forEach(s -> contentBuilder.append(s).append("\n"));
        return contentBuilder.toString();
    }
}

Mit dem folgenden SQL-Code wird die UDF erstellt. Dieser Code geht davon aus, dass der Java-Quellcode kompiliert und in einer JAR-Datei mit dem Namen TestReadRelativeFile.jar bereitgestellt wurde, die von der UDF importiert wird. Die zweite und die dritte importierte Datei, my_config_file_1.txt und my_config_file_2.txt, sind Konfigurationsdateien, die von der UDF gelesen werden können.

CREATE FUNCTION file_reader(file_name VARCHAR)
RETURNS VARCHAR
LANGUAGE JAVA
IMPORTS = ('@my_stage/my_package/TestReadRelativeFile.jar',
           '@my_stage/my_path/my_config_file_1.txt',
           '@my_stage/my_path/my_config_file_2.txt')
HANDLER = 'my_package.TestReadRelativeFile.readFile';

Der folgende Code ruft die UDF auf:

SELECT file_reader('my_config_file_1.txt') ...;
...
SELECT file_reader('my_config_file_2.txt') ...;

... imports = ('@MyStage/MyData.txt.gz', ...)

Lesen einer mit SnowflakeFile dynamisch spezifizierten Datei¶

Die Methoden der SnowflakeFile-Klasse können im Java-Handler-Code verwendet werden, um Dateien aus einem Stagingbereich zu lesen. Die SnowflakeFile-Klasse wird in den Klassenpfad aufgenommen, der in Snowflake für Java-UDF-Handler verfügbar ist.

Um Ihren UDF-Code lokal zu entwickeln, fügen Sie die Snowpark-JAR-Datei, die die SnowflakeFile-Klasse enthält, zum Klassenpfad Ihres Codes hinzu. Weitere Informationen zur snowpark.jar-Datei finden Sie unter Einrichten Ihrer Entwicklungsumgebung für Snowpark Java. Beachten Sie, dass Snowpark-Clientanwendungen diese Klasse nicht verwenden können.

Wenn Sie SnowflakeFile verwenden, ist es beim Erstellen der UDF nicht notwendig, in einer IMPORTS-Klausel die Stagingdatei bzw. die JAR-Datei, die SnowflakeFile enthält, anzugeben, wie dies in SQL mit einer CREATE FUNCTION-Anweisung erforderlich ist.

Im folgenden Codebeispiel wird SnowflakeFile verwendet, um eine Datei vom Speicherort des Stagingbereichs zu lesen. Mit InputStream aus der getInputStream-Methode wird der Inhalt der Datei in eine String-Variable gelesen.

CREATE OR REPLACE FUNCTION sum_total_sales(file string)
RETURNS INTEGER
LANGUAGE JAVA
HANDLER = 'SalesSum.sumTotalSales'
TARGET_PATH = '@jar_stage/sales_functions2.jar'
AS
$$
import java.io.InputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import com.snowflake.snowpark_java.types.SnowflakeFile;

public class SalesSum {

  public static int sumTotalSales(String filePath) throws IOException {
    int total = -1;

    // Use a SnowflakeFile instance to read sales data from a stage.
    SnowflakeFile file = SnowflakeFile.newInstance(filePath);
    InputStream stream = file.getInputStream();
    String contents = new String(stream.readAllBytes(), StandardCharsets.UTF_8);

    // Omitted for brevity: code to retrieve sales data from JSON and assign it to the total variable.

    return total;
  }
}
$$;

Rufen Sie die UDF auf, und übergeben Sie den Speicherort der Datei in einer Bereichs-URL, um die Wahrscheinlichkeit von Angriffen mittels Dateieinschleusung zu verringern.

SELECT sum_total_sales(BUILD_SCOPED_FILE_URL('@sales_data_stage', '/car_sales.json'));

String filename = "@my_stage/filename.txt";
String sfFile = SnowflakeFile.newInstance(filename, false);

Lesen einer mit InputStream dynamisch spezifizierten Datei¶

Sie können den Inhalt einer Datei direkt in einen java.io.InputStream-Eingabestream einlesen, indem Sie das Argument Ihrer Handler-Funktion als InputStream-Variable behandeln. Dies kann nützlich sein, wenn der Aufrufer der Funktion einen Dateipfad als Argument übergeben möchte.

Im folgenden Codebeispiel nimmt ein Handler-Funktion sumTotalSales einen InputStream-Wert entgegen und gibt einen int-Wert zurück. Zur Laufzeit weist Snowflake den Inhalt der Datei mit dem in der Variable file angegebenen Pfad automatisch der Argumentvariablen stream zu.

CREATE OR REPLACE FUNCTION sum_total_sales(file string)
RETURNS INTEGER
LANGUAGE JAVA
HANDLER = 'SalesSum.sumTotalSales'
TARGET_PATH = '@jar_stage/sales_functions2.jar'
AS
$$
import java.io.InputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

public class SalesSum {

  public static int sumTotalSales(InputStream stream) throws IOException {
    int total = -1;
    String contents = new String(stream.readAllBytes(), StandardCharsets.UTF_8);

    // Omitted for brevity: code to retrieve sales data from JSON and assign it to the total variable.

    return total;
  }
}
$$;

Rufen Sie die UDF auf, und übergeben Sie den Speicherort der Datei in einer Bereichs-URL, um die Wahrscheinlichkeit von Angriffen mittels Dateieinschleusung zu verringern.

SELECT sum_total_sales(BUILD_SCOPED_FILE_URL('@sales_data_stage', '/car_sales.json'));

Java-Handler-Code erstellen und kompilieren¶

1. Erstellen Sie im Stammverzeichnis Ihres Projekts (hier my_udf) ein Unterverzeichnis src, das die .java-Quelldateien enthält, sowie ein Unterverzeichnis classes, das die generierten .class-Dateien enthält.

   Die Verzeichnishierarchie sollte dann in etwa wie folgt aussehen:

   my_udf/
   |-- classes/
   |-- src/
   

   Copy

2. Erstellen Sie im Verzeichnis src ein Unterverzeichnis mit dem Namen mypackage, um .java-Dateien zu speichern, deren Klassen sich im mypackage-Paket befinden.

3. Erstellen Sie im Verzeichnis mypackage eine Datei MyUDFHandler.java, die Ihren Quellcode enthält.

   package mypackage;
   
   public class MyUDFHandler {
   
     public static int decrementValue(int i)
     {
         return i - 1;
     }
   
     public static void main(String[] argv)
     {
         System.out.println("This main() function won't be called.");
     }
   }
   

   Copy

4. Verwenden Sie in Ihrem Projektstammverzeichnis (hier my_udf) den Befehl javac, um den Quellcode zu kompilieren.

   Mit dem Befehl javac wird im folgenden Beispiel MyUDFHandler.java kompiliert, um eine Datei MyUDFHandler.class im Verzeichnis classes zu generieren.

   javac -d classes src/mypackage/MyUDFHandler.java
   

   Copy

   Dieses Beispiel enthält die folgenden Argumente:

   • -d classes – Verzeichnis, in das die generierten Klassendateien geschrieben werden sollen.

   • src/mypackage/MyUDFHandler.java – Pfad zur .java-Datei in der Form source_directory/package_directory/Java_file_name.

Kompilierten Code in JAR-Datei packen¶

1. Optional können Sie im Stammverzeichnis des Projekts eine Manifest-Datei mit dem Namen my_udf.manifest erstellen, die die folgenden Attribute enthält:

   Manifest-Version: 1.0
   Main-Class: mypackage.MyUDFHandler
   

   Copy

2. Führen Sie im Stammverzeichnis Ihres Projekts den Befehl jar aus, um eine JAR-Datei zu erstellen, die die .class-Datei und die Manifest-Datei enthält.

   Mit dem jar-Befehl im folgenden Beispiel wird die generierte Datei MyUDFHandler.class im Paketordner mypackage in einer .jar-Datei namens my_udf.jar abgelegt. Das Flag -C ./classes gibt den Speicherort der .class-Dateien an.

   jar cmf my_udf.manifest my_udf.jar -C ./classes mypackage/MyUDFHandler.class
   

   Copy

   Dieses Beispiel enthält die folgenden Argumente:

   • cmf – Befehlsargumente: c zum Erstellen einer JAR-Datei, m zum Verwenden der angegebenen Manifest-Datei und f zum Benennung der JAR-Datei mit dem angegebenen Namen.

   • my_udf.manifest – Manifest-Datei.

   • my_udf.jar – Name der zu erstellenden JAR-Datei.

   • -C ./classes – Verzeichnis, das die generierten .class-Dateien enthält.

   • mypackage/MyUDFHandler.class – Paket und Name der .class-Datei, die in die JAR-Datei eingebunden werden soll.

JAR-Datei mit kompiliertem Handler in Stagingbereich hochladen¶

1. Erstellen Sie in Snowflake einen Stagingbereich mit dem Namen jar_stage, in dem die JAR-Datei mit Ihrem UDF-Handler gespeichert werden soll.

   Weitere Informationen zum Erstellen eines Stagingbereichs finden Sie unter CREATE STAGE.

2. Verwenden Sie den PUT-Befehl, um die JAR-Datei aus dem lokalen Dateisystem in einen Stagingbereich zu kopieren.

put
    file:///Users/Me/my_udf/my_udf.jar
    @jar_stage
    auto_compress = false
    overwrite = true
    ;

Copy

Sie können den PUT-Befehl in einer Skriptdatei speichern und diese Datei dann über SnowSQL ausführen.

Der snowsql-Befehl sieht ungefähr wie folgt aus:

snowsql -a <account_identifier> -w <warehouse> -d <database> -s <schema> -u <user> -f put_command.sql

Copy

In diesem Beispiel wird davon ausgegangen, dass das Kennwort des Benutzers in der Umgebungsvariablen SNOWSQL_PWD angegeben ist.

UDF mit kompiliertem Code als Handler erstellen¶

Erstellen der UDF:

create function decrement_value(i numeric(9, 0))
  returns numeric
  language java
  imports = ('@jar_stage/my_udf.jar')
  handler = 'mypackage.MyUDFHandler.decrementValue'
  ;

Aufrufen der UDF:

select decrement_value(-15);
+----------------------+
| DECREMENT_VALUE(-15) |
|----------------------|
|                  -16 |
+----------------------+