UDFs Java tabulaires (UDTFs)¶

Notes sur l’utilisation du partitionnement¶

• Lorsqu’il reçoit des lignes qui sont implicitement partitionnées par Snowflake, votre code de gestionnaire ne peut pas faire d’hypothèses sur les partitions. L’exécution sans partitionnement implicite est particulièrement utile lorsque l’UDTF n’a que besoin d’examiner les lignes en isolation pour produire sa sortie, et aucun état n’est agrégé d’une ligne à l’autre. Dans ce cas, le code n’a probablement pas besoin d’un constructeur ou d’une méthode endPartition.

• Pour améliorer les performances, Snowflake exécute généralement plusieurs instances du code de gestion de l’UDTF en parallèle. Chaque partition de lignes est transmise à une seule instance de l’UDTF.

• Bien que chaque partition ne soit traitée que par une seule instance d’UDTF, l’inverse n’est pas nécessairement vrai – une seule instance d’UDTF peut traiter plusieurs partitions séquentiellement. Il est donc important d’utiliser l’initialiseur et le finaliseur pour initialiser et nettoyer chaque partition afin d’éviter de reporter les valeurs accumulées du traitement d’une partition au traitement d’une autre partition.

La classe de gestion¶

Snowflake interagit avec l’UDTF principalement en appelant les méthodes suivantes de la classe de gestion :

• L’initialiseur (le constructeur).

• La méthode par ligne (process).

• La méthode finaliseur (endPartition).

La classe de gestion peut contenir des méthodes supplémentaires nécessaires à la prise en charge de ces trois méthodes.

La classe de gestionnaire contient également une méthode getOutputClass, qui est décrite plus loin.

Le lancement d’une exception à partir de n’importe quelle méthode de la classe de gestion (ou de la ligne de sortie) entraîne l’arrêt du traitement. La requête qui a appelé l’UDTF échoue avec un message d’erreur.

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

La classe de ligne de sortie¶

Snowflake utilise la classe de ligne de sortie pour aider à spécifier les conversions entre les types de données Java et les types de données SQL.

Lorsqu’une UDTF Java renvoie une ligne, la valeur de chaque colonne de la ligne doit être convertie du type de données Java au type de données SQL correspondant. Les types de données SQL sont spécifiés dans la clause RETURNS de l’instruction CREATE FUNCTION. Toutefois, le mappage entre les types de données Java et SQL n’est pas de 1 pour 1, de sorte que Snowflake doit connaître le type de données Java pour chaque colonne renvoyée. (Pour plus d’informations sur le mappage de types de données SQL et Java, voir Mappages de type de données SQL-Java).

Une UDTF Java spécifie les types de données Java des colonnes de sortie en définissant une classe de ligne de sortie. Chaque ligne renvoyée par l’UDTF est renvoyée comme une instance de la classe de ligne de sortie. Chaque instance de la classe de ligne de sortie contient un champ public pour chaque colonne de sortie. Snowflake lit les valeurs des champs publics de chaque instance de la classe de ligne de sortie, convertit les valeurs Java en valeurs SQL et construit une ligne de sortie SQL contenant ces valeurs.

Les valeurs de chaque instance de la classe de ligne de sortie sont définies en appelant le constructeur de la classe de ligne de sortie. Le constructeur accepte les paramètres qui correspondent aux colonnes de sortie, puis définit les champs publics en fonction de ces paramètres.

Le code ci-dessous définit un exemple de classe de ligne de sortie :

class OutputRow {

  public String name;
  public int id;

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

}

Les variables publiques spécifiées par cette classe doivent correspondre aux colonnes spécifiées dans la clause RETURNS TABLE (...) de l’instruction CREATE FUNCTION. Par exemple, la classe OutputRow ci-dessus correspond à la clause RETURNS ci-dessous :

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

La classe de lignes de sortie est utilisée comme suit :

• La classe de gestion utilise la classe de ligne de sortie pour spécifier le type de retour de la méthode process et de la méthode endPartition. La classe de gestion utilise également la classe de ligne de sortie pour construire les valeurs retournées. Par exemple :

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

  Copy

• La classe de ligne de sortie est également utilisée dans la méthode getOutputClass de la classe de gestion, qui est une méthode statique que Snowflake appelle afin d’apprendre les types de données Java des sorties :

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

  Copy

Le lancement d’une exception à partir de n’importe quelle méthode de la classe de ligne de sortie (ou de la classe de gestionnaire) entraîne l’arrêt du traitement. La requête qui a appelé l’UDTF échoue avec un message d’erreur.

Résumé des exigences¶

Le code Java de l’UDTF doit répondre aux exigences suivantes :

• Le code doit définir une classe de ligne de sortie.

• La classe de gestion de l’UDTF doit inclure une méthode publique nommée process qui renvoie un flux <output_row_class>, où le flux (Stream) est défini dans java.util.stream.Stream.

• La classe de gestion de l’UDTF doit définir une méthode statique publique nommée getOutputClass, qui doit renvoyer <output_row_class>.class.

Si le code Java ne répond pas à ces exigences, la création ou l’exécution de l’UDTF échoue :

• Si la session a un entrepôt actif au moment où l’instruction CREATE FUNCTION s’exécute, alors Snowflake détecte des violations lors de la création de la fonction.

• Si la session n’a pas d’entrepôt actif au moment où l’instruction CREATE FUNCTION est exécutée, Snowflake détecte des violations lorsque la fonction est appelée.

Appel sans partitionnement explicite¶

Cet exemple montre comment créer une UDTF. Cet exemple renvoie deux copies de chaque entrée et renvoie une ligne supplémentaire pour chaque partition.

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

  }

$$;

Cet exemple montre comment appeler une UDTF. Pour que cet exemple reste simple, l’instruction transmet une valeur littérale plutôt qu’une colonne et omet la clause OVER().

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

Cet exemple appelle l’UDTF avec des valeurs lues à partir d’une autre table. Chaque fois que la méthode process est appelée, on lui transmet une valeur de la colonne city_name de la ligne actuelle de la table cities_of_interest. Comme ci-dessus, l’UDTF est appelée sans clause OVER() explicite.

Créez une table simple à utiliser comme source de données :

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

Appelez l’UDTF Java :

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() |
+-----------+-------------------------------------------------------+

La section d’exemples de la documentation des UDTFs JavaScript contient des exemples plus complexes de requêtes qui appellent des UDTFs avec des valeurs provenant de tables.

Si l’instruction ne spécifie pas explicitement le partitionnement, le moteur d’exécution Snowflake utilise le partitionnement implicite.

S’il n’y a qu’une seule partition, la méthode endPartition n’est appelée qu’une seule fois et la sortie de la requête ne comprend qu’une seule ligne contenant la valeur Created in constructor and output from endPartition(). Si les données sont regroupées en un nombre différent de partitions lors des différentes exécutions de l’instruction, la méthode endPartition est appelée un nombre différent de fois, et la sortie contient un nombre différent de copies de cette ligne.

Pour plus d’informations, voir partitionnement implicite.

Appel avec partitionnement explicite¶

Les UDTFs Java peuvent également être appelées en utilisant un partitionnement explicite.

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() |
+-----------+-------------------------------------------------------+

Traitement d’entrées très volumineuses (par exemple, des fichiers volumineux)¶

Dans certains cas, une UDTF nécessite une très grande quantité de mémoire pour traiter chaque ligne d’entrée. Par exemple, une UDTF peut lire et traiter un fichier trop volumineux pour tenir dans la mémoire.

Pour traiter des fichiers volumineux dans une UDF ou une UDTF, utilisez la classe SnowflakeFile ou InputStream. Pour plus d’informations, voir Traitement de données non structurées avec des gestionnaires d’UDF et de procédures.