MaxCompute:Développement d'UDF en Java

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

• Évitez d'inclure des classes portant le même nom mais implémentant une logique différente dans différents fichiers JAR d'UDF. Par exemple, si UDF1 et UDF2 correspondent respectivement à udf1.jar et udf2.jar, et que les deux fichiers JAR contiennent com.aliyun.UserFunction.class avec une logique différente, l'appel simultané des deux UDF dans la même instruction SQL amène MaxCompute à charger aléatoirement l'une des classes. Cela peut entraîner des résultats inattendus ou un échec de compilation.

• Dans une UDF Java, les paramètres d'entrée et les valeurs de retour doivent utiliser des types objet (tels que String et Long), et non des types primitifs (tels que int et long).

• Les valeurs NULL en SQL correspondent à NULL en Java. Les types primitifs Java ne pouvant pas représenter les valeurs NULL, leur utilisation n'est pas autorisée.

Une fois que vous avez développé une UDF Java comme décrit dans le flux de travail de développement d'UDF, vous pouvez l'appeler dans SQL MaxCompute. Les méthodes suivantes sont disponibles :

• Au sein d'un projet — Appelez l'UDF directement, comme toute fonction intégrée.

• Entre projets — Pour utiliser une UDF du projet B dans le projet A, référencez-la avec le préfixe du projet :

  select B:udf_in_other_project(arg0, arg1) as res from table_t;

  Pour la configuration du partage interprojets, consultez Accès aux ressources interprojets basé sur les packages.

Une UDF Java se compose des éléments suivants :

• Package Java : Facultatif.

  Vous pouvez regrouper vos classes Java dans un package pour faciliter leur réutilisation et leur organisation.

• Héritage de la classe UDF : Obligatoire.

  La classe de base requise est com.aliyun.odps.udf.UDF. Si vous avez besoin d'autres classes UDF ou de types de données complexes, ajoutez les classes requises du SDK MaxCompute. Par exemple, la classe pour le type de données STRUCT est com.aliyun.odps.data.Struct.

• Annotation @Resolve : Facultative.

  Le format est @Resolve(<signature>), où signature définit les types de données des paramètres d'entrée et de la valeur de retour. Lorsque vous utilisez le type de données STRUCT dans une UDF, la réflexion ne permet pas de récupérer les noms et les types de champs depuis com.aliyun.odps.data.Struct. Dans ce cas, vous devez utiliser l'annotation @Resolve pour les récupérer. Si vous utilisez STRUCT dans une UDF, ajoutez l'annotation @Resolve à la classe UDF. L'annotation affecte uniquement les surcharges dont les paramètres ou les valeurs de retour contiennent com.aliyun.odps.data.Struct. Exemple : @Resolve("struct<a:string>,string->string"). Pour un exemple détaillé, consultez Exemple d'UDF : Types de données complexes.

• Classe Java personnalisée : Obligatoire.

  Il s'agit de l'unité qui organise votre code UDF et définit les variables et méthodes implémentant votre logique métier.

• Méthode evaluate : Obligatoire.

  Votre classe Java personnalisée doit inclure une méthode publique non statique evaluate. Les types de données de ses paramètres d'entrée et de sa valeur de retour définissent la signature SQL de l'UDF.

  Vous pouvez implémenter plusieurs méthodes evaluate. Lors de l'appel de l'UDF, MaxCompute sélectionne la méthode evaluate correspondante en fonction des types d'arguments.

  Lorsque vous écrivez une UDF Java, vous pouvez utiliser des types Java ou des types Java Writable. Pour les correspondances détaillées entre les types de données MaxCompute et les types de données Java, consultez l'Annexe : Types de données.

• Initialisation et nettoyage de l'UDF : Facultatifs. Vous pouvez implémenter l'initialisation et le nettoyage à l'aide de void setup(ExecutionContext ctx) et void close(). La méthode void setup(ExecutionContext ctx) est appelée une fois avant la méthode evaluate et peut être utilisée pour initialiser les ressources ou les objets membres requis pour le calcul. La méthode void close() est appelée une fois après l'exécution de tous les appels evaluate et sert aux tâches de nettoyage, telles que la fermeture de fichiers.

Les exemples suivants montrent deux types d'UDF.

• Utiliser des types Java

  // Organize the Java class in the org.alidata.odps.udf.examples package.
  package org.alidata.odps.udf.examples;  
  // Inherit the UDF class.
  import com.aliyun.odps.udf.UDF;         
  // Define a custom Java class.
  public final class Lower extends UDF { 
  // The evaluate method defines the UDF's logic. It takes a String and returns a String.
      public String evaluate(String s) { 
          if (s == null) { 
          return null; 
      } 
          return s.toLowerCase(); 
    } 
  }

• Utiliser des types Java Writable

  // Organize the Java class in the com.aliyun.odps.udf.example package.
  package com.aliyun.odps.udf.example;
  // Add the required classes for the Java Writable type.
  import com.aliyun.odps.io.Text;
  // Inherit the UDF class.
  import com.aliyun.odps.udf.UDF;
  // Define a custom Java class.
  public class MyConcat extends UDF {
    private Text ret = new Text();
  // Define the evaluate method. `Text` specifies the data type of the input parameters, and the `return` value is also a Text object.
    public Text evaluate(Text a, Text b) {
        if (a == null || b == null) {
        return null;
      }
        ret.clear();
        ret.append(a.getBytes(), 0, a.getLength());
        ret.append(b.getBytes(), 0, b.getLength());
        return ret;
    }
  }

Correspondances de types de données

Pour garantir la cohérence entre les types de données utilisés dans une UDF Java et les types de données MaxCompute, utilisez les correspondances suivantes.

Le type Java byte[] ne figure pas dans la liste des types Java pris en charge. Si vous utilisez byte[] pour un paramètre d'entrée ou la valeur de retour d'une méthode evaluate, une erreur ODPS-0130071 est signalée. Pour traiter des données binaires dans une UDF, utilisez les types Java correspondant au type BINARY de MaxCompute : com.aliyun.odps.data.Binary pour le type Java standard, ou com.aliyun.odps.io.BytesWritable pour le type Writable. Vous pouvez également convertir les données binaires en une chaîne encodée en Base64 et utiliser le type String pour la valeur de retour.

Compatibilité des UDF Hive

Si votre projet MaxCompute utilise l'édition de type de données 2.0, MaxCompute prend en charge les UDF de style Hive. Vous pouvez utiliser directement les UDF Hive développées pour une version Hive compatible.

La version Hive compatible est la 2.1.0, qui correspond à Hadoop 2.7.2. Si votre UDF a été compilée avec une version différente de Hive ou Hadoop, recompilez le fichier JAR de l'UDF avec Hive 2.1.0 ou Hadoop 2.7.2.

Pour un exemple détaillé d'utilisation d'une UDF Hive dans MaxCompute, consultez Exemple d'UDF : Compatibilité Hive.