MaxCompute:Développement de fonctions UDF en Java

Lors de l'écriture d'une UDF en Java, tenez compte des points suivants :

• Évitez d'inclure des classes portant le même nom mais implémentant des logiques différentes dans plusieurs fichiers JAR d'UDF. Par exemple, si UDF1 et UDF2 correspondent respectivement à udf1.jar et udf2.jar, et que ces deux fichiers JAR contiennent com.aliyun.UserFunction.class avec des logiques distinctes, l'appel simultané des deux UDF dans une même instruction SQL amène MaxCompute à charger l'une des classes de manière aléatoire. Ce comportement 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 (comme String et Long), et non des types primitifs (comme int et long).

• Les valeurs NULL en SQL correspondent à NULL en Java. Les types primitifs Java ne pouvant pas représenter de valeurs NULL, leur utilisation est interdite.

Une fois l'UDF Java développée selon le flux de développement d'une UDF, appelez-la dans MaxCompute SQL. Deux méthodes s'offrent à vous :

• Utilisation d'une UDF dans un projet MaxCompute : cette méthode s'apparente à celle des fonctions intégrées. Une fonction définie par l'utilisateur s'emploie exactement comme une fonction intégrée.

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

• Écrire une UDF Hive en Java

• Utiliser des types de données complexes dans des UDF Java

• Remplacer des chaînes à l'aide d'expressions régulières

• Obtenir les valeurs de chaînes sans délimiteurs

• Obtenir les valeurs de chaînes avec délimiteurs

• Référencer une ressource de fichier

• Référencer une ressource de table

• Référencer des packages tiers dans des UDF Python

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

• Package Java : facultatif.

  Regroupez vos classes Java dans un package afin de 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 nécessaires depuis le SDK MaxCompute. Par exemple, la classe correspondant au type de données STRUCT est com.aliyun.odps.data.Struct.

• Annotation @Resolve : facultative.

  Son 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. Lorsqu'une UDF utilise le type de données STRUCT, la réflexion ne permet pas de récupérer les noms et les types des champs depuis com.aliyun.odps.data.Struct. Dans ce cas, recourez à l'annotation @Resolve pour les obtenir. Si votre UDF manipule le type STRUCT, ajoutez l'annotation @Resolve à la classe de l'UDF. Cette annotation n'affecte que 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.

  Cette unité structure le code de votre UDF et définit les variables ainsi que les méthodes qui mettent en œuvre votre logique métier.

• Méthode evaluate : obligatoire.

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

  Plusieurs méthodes evaluate peuvent coexister. Lors de l'appel de l'UDF, MaxCompute sélectionne la méthode evaluate correspondant aux types des arguments fournis.

  Lors de la rédaction d'une UDF Java, utilisez indifféremment des types Java ou des types Java Writable. Pour connaître les correspondances détaillées entre les types de données MaxCompute et Java, consultez Annexe : Types de données.

• Initialisation et nettoyage de l'UDF : facultatifs. Mettez-les en œuvre à l'aide de void setup(ExecutionContext ctx) et void close(). La méthode void setup(ExecutionContext ctx) s'exécute une seule fois avant la méthode evaluate ; elle sert à initialiser les ressources ou les objets membres nécessaires au calcul. Quant à la méthode void close(), elle intervient une fois après l'ensemble des appels à evaluate et prend en charge les tâches de nettoyage, comme la fermeture des fichiers.

Les exemples suivants illustrent deux catégories d'UDF.

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

• Avec 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 des types de données

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

Le type Java byte[] ne figure pas parmi les types Java pris en charge. Si vous utilisez byte[] comme paramètre d'entrée ou valeur de retour d'une méthode evaluate, l'erreur ODPS-0130071 est signalée. Pour traiter des données binaires dans une UDF, employez 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 chaîne encodée en Base64 et utiliser le type String comme valeur de retour.

Compatibilité des UDF Hive

Si votre projet MaxCompute utilise l'édition de types de données 2,0, MaxCompute prend en charge les UDF de style Hive. Vous pouvez ainsi employer directement les UDF Hive développées pour une version compatible de Hive.

La version compatible de Hive est la 2.1.0, qui correspond à Hadoop 2.7.2. Si votre UDF a été compilée avec une autre version de Hive ou de Hadoop, recompilez le fichier JAR de l'UDF sous 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.