Exemples de gestionnaires d’UDF Java¶

Transmission d’un NULL à une UDF Java en ligne¶

Ceci utilise les echo_varchar() UDF définies ci-dessus. La valeur SQL NULL est implicitement convertie en null Java, et cette null Java est retournée et implicitement reconvertie au format SQL NULL :

Appelez l’UDF :

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

Transmission par un ARRAY¶

Déclarez le paramètre Java comme un tableau. Par exemple, le troisième paramètre de la méthode suivante est un tableau Chaîne :

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

Copy

Vous trouverez ci-dessous un exemple complet :

Créer et charger la table :

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

Créez l’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

Appelez l’UDF :

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

Copy

Transmission par des Varargs¶

L’utilisation de varargs est très similaire à celle d’un tableau.

Dans votre code Java, utilisez le style de déclaration varargs de Java :

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

Copy

Vous trouverez ci-dessous un exemple complet. La seule différence significative entre cet exemple et l’exemple précédent (pour les tableaux) est la déclaration des paramètres de la méthode.

Créer et charger la table :

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

Créez l’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

Appelez l’UDF :

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

Copy

Conditions préalables¶

Avant que votre code de gestionnaire Java puisse lire un fichier sur une zone de préparation, vous devez effectuer les opérations suivantes pour mettre le fichier à la disposition du code :

1. Créez une zone de préparation qui est disponible pour votre gestionnaire.

   Vous pouvez utiliser une zone de préparation externe ou une zone de préparation interne. Si vous utilisez une zone de préparation interne, il doit s’agir d’une zone de préparation d’utilisateur ou nommée ; Snowflake ne prend actuellement pas en charge l’utilisation d’une zone de préparation de table pour des dépendances d’UDF. Pour en savoir plus sur la création d’une zone de préparation, voir CREATE STAGE. Pour en savoir plus sur le choix d’un type de zone de préparation interne, voir Sélection d’une zone de préparation interne pour les fichiers locaux.

   Gardez à l’esprit que des privilèges adéquats sur la zone de préparation doivent être attribués aux rôles effectuant des actions SQL qui effectuent des lectures à partir de la zone de préparation. Pour plus d’informations, voir Granting Privileges for User-Defined Functions.

2. Sur la zone de préparation, copiez le fichier qui sera lu par le code.

   Vous pouvez copier le fichier d’un lecteur local vers une zone de préparation en utilisant la commande PUT. Pour la référence de la commande, voir PUT. Pour des informations sur la mise en zone de préparation de fichiers avec PUT, voir Mise en zone de préparation de fichiers de données à partir d’un système de fichiers local.

Lecture d’un fichier spécifié statiquement dans IMPORTS¶

Votre gestionnaire peut lire un fichier dont le chemin de zone de préparation a été spécifié dans la clause IMPORTS de la commande CREATE FUNCTION.

Lorsque vous spécifiez un fichier dans la clause IMPORTS, Snowflake copie ce fichier de la zone de préparation vers le répertoire personnel (également appelé répertoire d’importation) de l’UDF, qui est le répertoire à partir duquel l’UDF lit réellement le fichier.

Étant donné que les fichiers importés sont copiés dans un seul répertoire et qu’ils doivent avoir des noms uniques au sein de ce répertoire, chaque fichier de la clause IMPORTS doit avoir un nom distinct, même si les fichiers commencent dans différentes zones de préparation ou différents sous-répertoires au sein d’une zone de préparation.

L’exemple suivant crée et appelle une UDF Java qui lit un fichier :

Le code source Java ci-dessous crée une méthode Java nommée readFile. Cette UDF utilise cette méthode.

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();
    }
}

Le code SQL suivant crée l” UDF. Ce code suppose que le code source Java a été compilé et placé dans un fichier JAR nommé TestReadRelativeFile.jar, que l’UDF importe. Les deuxième et troisième fichiers importés, my_config_file_1.txt et my_config_file_2.txt, sont des fichiers de configuration que l’UDF peut lire.

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';

Ce code appelle l’UDF :

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

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

Lecture d’un fichier spécifié de façon dynamique avec SnowflakeFile¶

En utilisant les méthodes de la classe SnowflakeFile, vous pouvez lire les fichiers d’une zone de préparation avec votre code de gestionnaire Java. La classe SnowflakeFile est incluse dans le classpath accessible aux gestionnaires d’UDF Java sur Snowflake.

Pour développer le code de votre UDF localement, ajoutez le fichier JAR Snowpark contenant SnowflakeFile au chemin de classe de votre code. Pour plus d’informations sur snowpark.jar, voir Configuration de votre environnement de développement pour Snowpark Java. Notez que les applications clientes Snowpark ne peuvent pas utiliser cette classe.

Lorsque vous utilisez SnowflakeFile, il n’est pas nécessaire de spécifier également le fichier en zone de préparation ou le fichier JAR contenant SnowflakeFile avec une clause IMPORTS lorsque vous créez l’UDF, comme dans SQL avec une instruction CREATE FUNCTION.

Le code de l’exemple suivant utilise SnowflakeFile pour lire un fichier à partir d’un emplacement de zone de préparation spécifié. En utilisant un InputStream à partir de la méthode getInputStream, il lit le contenu du fichier dans une variable String.

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;
  }
}
$$;

Appelez l’UDF, en transmettant l’emplacement du fichier dans une URL scopée pour réduire la probabilité d’attaques par injection de fichier.

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);

Lecture d’un fichier spécifié de façon dynamique avec InputStream¶

Vous pouvez lire le contenu du fichier directement dans un java.io.InputStream en faisant de l’argument de votre fonction de traitement une variable InputStream. Cela peut être utile lorsque l’appelant de la fonction veut passer un chemin de fichier comme argument.

Le code de l’exemple suivant comporte une fonction de gestionnaire sumTotalSales qui prend un InputStream et renvoie un int. Au moment de l’exécution, Snowflake attribue automatiquement le contenu du fichier au chemin d’accès de la variable file à la variable de l’argument stream.

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;
  }
}
$$;

Appelez l’UDF, en transmettant l’emplacement du fichier dans une URL scopée pour réduire la probabilité d’attaques par injection de fichier.

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

Créer et compiler le code du gestionnaire Java¶

1. Dans le répertoire racine de votre projet (ici, my_udf), créez un sous-répertoire src pour contenir les fichiers .java source et un sous-répertoire classes pour contenir les fichiers .class générés.

   Vous devriez avoir une hiérarchie de répertoires semblable à la suivante :

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

   Copy

2. Dans le répertoire src , créez un répertoire appelé mypackage pour contenir les fichiers .java dont les classes sont dans le package mypackage.

3. Dans le répertoire mypackage , créez un fichier MyUDFHandler.java qui contient votre code source.

   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. Depuis le répertoire racine de votre projet (ici, my_udf), utilisez la commande javac pour compiler le code source.

   La commande javac de l’exemple suivant compile MyUDFHandler.java pour générer un fichier MyUDFHandler.class dans le répertoire classes.

   javac -d classes src/mypackage/MyUDFHandler.java
   

   Copy

   Cet exemple comprend les arguments suivants :

   • -d classes – Répertoire dans lequel les fichiers de classe générés doivent être écrits.

   • src/mypackage/MyUDFHandler.java – Chemin du fichier .java sous la forme : source_directory/package_directory/Java_file_name.

Empaqueter le code compilé dans un fichier JAR¶

1. En option, dans le répertoire racine du projet, créez un fichier manifeste nommé my_udf.manifest qui contient les attributs suivants :

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

   Copy

2. À partir du répertoire racine de votre projet, exécutez la commande jar pour créer un fichier JAR contenant le fichier .class et le manifeste.

   La commande jar de l’exemple suivant place le fichier MyUDFHandler.class généré dans un dossier de package mypackage dans un fichier .jar appelé my_udf.jar. L’indicateur -C ./classes spécifie l’emplacement des fichiers .class.

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

   Copy

   Cet exemple comprend les arguments suivants :

   • cmf – Arguments de la commande : c pour créer un fichier JAR, m pour utiliser le fichier .manifest spécifié, et f pour donner au fichier JAR le nom spécifié.

   • my_udf.manifest – Fichier manifeste.

   • my_udf.jar – Nom du fichier JAR à créer.

   • -C ./classes – Répertoire contenant les fichiers .class générés.

   • mypackage/MyUDFHandler.class – Package et nom du fichier .class à inclure dans le JAR.

Charger le fichier JAR avec le gestionnaire compilé vers une zone de préparation¶

1. Dans Snowflake, créez une zone de préparation appelée jar_stage pour stocker le fichier JAR contenant votre gestionnaire UDF.

   Pour plus d’informations sur la création d’une zone de préparation, voir CREATE STAGE.

2. Utilisez la commande PUT pour copier le fichier JAR du système de fichiers local vers une zone de préparation.

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

Copy

Vous pouvez stocker la commande PUT dans un fichier de script, puis exécuter ce fichier via SnowSQL.

La commande snowsql doit être similaire à ce qui suit :

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

Copy

Cet exemple suppose que le mot de passe de l’utilisateur est spécifié dans la variable d’environnement SNOWSQL_PWD.

Créer l’UDF avec le code compilé comme gestionnaire¶

Créez l’UDF :

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

Appelez l’UDF :

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