MaxCompute:UDTF Java

Vous pouvez écrire le code UDTF en Java à l'aide d'IntelliJ IDEA (Maven) ou de MaxCompute Studio. Le code doit inclure les composants suivants :

• Package Java : facultatif.

  Organisez vos classes Java dans un package afin de faciliter leur recherche et leur utilisation.

• Extension de la classe UDTF : obligatoire.

  Les classes requises sont com.aliyun.odps.udf.UDTF, com.aliyun.odps.udf.annotation.Resolve (pour l'annotation @Resolve) et com.aliyun.odps.udf.UDFException (pour les méthodes de la classe Java). Si vous devez utiliser d'autres classes UDTF ou des types de données complexes, ajoutez les classes requises conformément à la section Présentation des UDF MaxCompute.

• Classe Java personnalisée : obligatoire.

  Il s'agit de l'unité organisationnelle du code UDTF. Elle définit les variables et les méthodes qui mettent en œuvre votre logique métier.

• Annotation @Resolve : obligatoire.

  Le format est @Resolve(<signature>). La signature est une signature de fonction qui définit les types de données des paramètres d'entrée et de la valeur de retour. Une UDTF ne peut pas obtenir la signature de fonction par réflexion et doit utiliser l'annotation @Resolve pour la spécifier, par exemple @Resolve("smallint->varchar(10)"). Pour plus d'informations sur l'annotation @Resolve, consultez la section Annotation @Resolve.

• Implémentation des méthodes dans la classe Java : obligatoire.

  L'implémentation de la classe Java comprend les quatre méthodes suivantes. Implémentez-les selon vos besoins.

  API	Description
  public void setup(ExecutionContext ctx) throws UDFException	La méthode d'initialisation. MaxCompute appelle votre logique d'initialisation personnalisée avant que l'UDTF ne commence à traiter les données d'entrée. La méthode setup est appelée une fois par worker.
  public void process(Object[] args) throws UDFException	La fonction process est appelée une fois pour chaque enregistrement d'une requête SQL. Les paramètres de la fonction process correspondent aux paramètres d'entrée spécifiés pour l'UDTF dans l'instruction SQL. Les paramètres d'entrée sont transmis sous forme de tableau Object[] et la sortie est générée à l'aide de la fonction forward. Vous devez appeler la fonction forward au sein de la fonction process pour déterminer la sortie. Remarque L'absence d'appel à forward depuis la méthode process ou close peut entraîner une perte de données. Par exemple, si un thread d'arrière-plan exécute un appel forward, vous devez vous assurer que la méthode process ne se termine pas tant que l'appel forward n'est pas terminé afin d'éviter toute perte de données.
  public void close() throws UDFException	La méthode de terminaison de l'UDTF. Elle n'est appelée qu'une seule fois, après le traitement du dernier enregistrement.
  public void forward(Object …o) throws UDFException	Appelez la méthode forward pour produire des données ; chaque appel à forward génère un enregistrement. Lorsque vous appelez une UDTF dans une requête SQL, vous pouvez utiliser la clause as pour renommer la sortie de forward.

  Lors de l'écriture d'une UDTF Java, vous pouvez utiliser Java Type ou Java Writable Type. Pour un mappage détaillé entre les types de données pris en charge par MaxCompute et les types de données Java, consultez la section Types de données.

// Organize the defined Java class in the org.alidata.odps.udtf.examples package.
package org.alidata.odps.udtf.examples;
// Extend the UDTF class.
import com.aliyun.odps.udf.UDTF;
import com.aliyun.odps.udf.UDTFCollector;
import com.aliyun.odps.udf.annotation.Resolve;
import com.aliyun.odps.udf.UDFException;
// Custom Java class.
//@Resolve annotation.
@Resolve("string,bigint->string,bigint")
public class MyUDTF extends UDTF {     
     // Implement the methods of the Java class.
     @Override
     public void process(Object[] args) throws UDFException {
         String a = (String) args[0];
         Long b = (Long) args[1];
         for (String t: a.split("\\s+")) {
         forward(t, b);
       }
     }
   }

Lorsque vous écrivez une UDTF Java, tenez compte des points suivants :

• Évitez de définir des classes portant le même nom mais ayant une logique d'implémentation différente dans différents packages JAR UDTF. Par exemple, supposons que UDTF1 et UDTF2 correspondent respectivement aux ressources de package JAR udtf1.jar et udtf2.jar. Si les deux packages JAR contiennent une classe nommée com.aliyun.UserFunction.class avec une logique différente, MaxCompute charge aléatoirement l'une des classes lorsque UDTF1 et UDTF2 sont appelées dans la même instruction SQL. Cela peut entraîner des résultats inattendus ou des échecs de compilation.

• Les paramètres d'entrée et les valeurs de retour doivent utiliser des types d'objets Java, tels que String et Long, plutôt que des types primitifs.

• En effet, les valeurs SQL NULL sont transmises en tant que null Java, ce que les types primitifs ne peuvent pas représenter.

Le format de l'annotation @Resolve est le suivant.

@Resolve(<signature>)

La chaîne signature spécifie les types de données des paramètres d'entrée et des valeurs de retour de l'UDTF. Lors de l'analyse de la requête, MaxCompute valide les appels par rapport à cette signature et signale une erreur en cas d'incompatibilité de type. Le format est le suivant.

'arg_type_list -> type_list'

Où :

• type_list : représente les types de données des valeurs de retour. Une UDTF peut renvoyer plusieurs colonnes. Les types de données pris en charge sont BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(precision,scale), les types de données complexes (ARRAY, MAP, STRUCT) et les types de données complexes imbriqués.

• arg_type_list : représente les types de données des paramètres d'entrée. Plusieurs paramètres d'entrée peuvent être spécifiés, séparés par des virgules (,). Les types de données pris en charge sont BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(precision,scale), CHAR, VARCHAR, les types de données complexes (ARRAY, MAP, STRUCT) et les types de données complexes imbriqués.

  La arg_type_list prend également en charge un astérisque (*) ou une chaîne vide ('').

  • Si la arg_type_list est un astérisque (*), cela indique que la fonction accepte n'importe quel nombre de paramètres d'entrée.

  • Si la arg_type_list est une chaîne vide (''), cela indique que la fonction n'a aucun paramètre d'entrée.

  Pour plus d'informations sur la syntaxe étendue de l'annotation Resolve, consultez la section Paramètres dynamiques pour les UDAF et les UDTF.

Après avoir développé une UDTF Java en suivant le processus de développement, vous pouvez l'appeler dans MaxCompute SQL.

• Utilisation d'une UDF dans un projet MaxCompute : la méthode est similaire à celle de l'utilisation des fonctions intégrées. Vous pouvez utiliser une fonction définie par l'utilisateur de la même manière qu'une fonction intégrée.

• Utilisation d'une UDF entre projets : utilisez une UDF du projet B dans le projet A. L'instruction suivante montre un exemple : select B:udf_in_other_project(arg0, arg1) as res from table_t;. Pour plus d'informations sur le partage interprojets, consultez la section Accès aux ressources interprojets basé sur les packages.