MaxCompute:UDAF Python 3

Utilisez MaxCompute Studio pour écrire le code d'une fonction d'agrégation définie par l'utilisateur (UDAF) en Python 3. Le code doit contenir les éléments suivants :

• Importation des modules : obligatoire.

  Importez au minimum from odps.udf import annotate et from odps.udf import BaseUDAF. L'instruction from odps.udf import annotate importe le module de signature de fonction, ce qui permet à MaxCompute de reconnaître la signature définie dans le code. from odps.udf import BaseUDAF importe la classe de base des UDAF Python. Implémentez des méthodes telles que iterate, merge et terminate dans la classe dérivée.

  Si le code UDAF doit référencer des ressources de type fichier ou table, incluez from odps.distcache import get_cache_file pour les ressources de type fichier ou from odps.distcache import get_cache_table pour les ressources de type table.

• Signature de fonction : obligatoire.

  Le format est @annotate(<signature>). La signature définit les types de données des paramètres d'entrée et de la valeur de retour de la fonction. Pour plus d'informations sur les signatures de fonction, consultez la section Signature de fonction et types de données.

• Classe Python personnalisée (classe dérivée) : obligatoire.

  Cette classe constitue l'unité organisationnelle du code UDAF. Elle définit les variables et les méthodes qui mettent en œuvre votre logique métier. Vous pouvez également référencer des bibliothèques tierces intégrées, des fichiers ou des ressources de type table dans votre code. Pour plus d'informations, consultez les sections Bibliothèques tierces ou Référencer des ressources.

• Implémentation des méthodes de la classe Python : obligatoire.

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

  Définition de la méthode	Description
  BaseUDAF.new_buffer()	Renvoie un tampon pour la valeur intermédiaire de la fonction d'agrégation. Le buffer doit être un objet Marshal, tel qu'une LIST ou un DICT. La taille du buffer ne doit pas augmenter avec le volume de données. Dans les cas extrêmes, la taille du buffer après sérialisation de l'objet ne doit pas dépasser 2 Mo.
  BaseUDAF.iterate(buffer[, args, ...])	Agrège les args dans la valeur intermédiaire buffer.
  BaseUDAF.merge(buffer, pbuffer)	Fusionne les valeurs intermédiaires buffer et pbuffer et stocke le résultat dans buffer.
  BaseUDAF.terminate(buffer)	Convertit le buffer en un type de données primitif de MaxCompute SQL.

Le code suivant fournit un exemple d'UDAF.

# Import the function signature module and the base class.
from odps.udf import annotate
from odps.udf import BaseUDAF
# Function signature.
@annotate('double->double')
# Custom Python class.
class Average(BaseUDAF):
# Implement the methods of the Python class.
    def new_buffer(self):
        return [0, 0]
    def iterate(self, buffer, number):
        if number is not None:
            buffer[0] += number
            buffer[1] += 1
    def merge(self, buffer, pbuffer):
        buffer[0] += pbuffer[0]
        buffer[1] += pbuffer[1]
    def terminate(self, buffer):
        if buffer[1] == 0:
            return 0.0
        return buffer[0] / buffer[1]

La figure suivante illustre la logique d'implémentation et le flux de calcul d'une UDAF MaxCompute pour le calcul de la valeur moyenne (

avg

).

pbuffer

correspond à

pr

dans la figure, et

buffer

correspond à

r

.

La Python Software Foundation cessera bientôt de maintenir Python 2. Nous vous recommandons de migrer vos projets en fonction du type de projet :

• Nouveaux projets : cela s'applique aux nouveaux projets MaxCompute ou aux projets MaxCompute dans lesquels vous écrivez une UDAF Python pour la première fois. Nous vous recommandons d'écrire toutes les UDAF Python en Python 3.

• Projets existants : cela s'applique aux projets MaxCompute qui comportent de nombreuses UDAF Python 2 existantes. Activez Python 3 avec prudence. Si vous prévoyez de migrer progressivement toutes les UDAF Python 2 vers Python 3, utilisez les méthodes suivantes :

  • Nouvelles tâches et nouvelles UDAF : écrivez-les en Python 3 et activez Python 3 au niveau de la session. Pour plus d'informations sur l'activation de Python 3, consultez la section Activer Python 3.

  • UDAF Python 2 : réécrivez les UDAF Python 2 afin qu'elles soient compatibles avec Python 2 et Python 3. Pour plus d'informations sur la réécriture du code, consultez la page Porting Python 2 Code to Python 3.

    Remarque

    Si vous souhaitez écrire une UDAF publique et accorder des permissions à plusieurs projets MaxCompute pour l'utiliser, nous vous recommandons de rendre l'UDAF compatible avec Python 2 et Python 3.

set odps.sql.python.version=cp37;

La signature de fonction possède le format suivant.

@annotate(<signature>)

signature

est une chaîne qui identifie les types de données des paramètres d'entrée et de la valeur de retour. Lors de l'exécution d'une UDAF, les types de données de ses paramètres d'entrée et de sa valeur de retour doivent correspondre aux types spécifiés dans la signature de fonction. Pendant la phase d'analyse de la requête, le système valide l'appel de fonction par rapport à la signature. En cas d'incompatibilité de type, une erreur est signalée. Le format spécifique est le suivant.

'arg_type_list -> type'

où :

• 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.

  arg_type_list accepte également un astérisque (*) ou une chaîne vide ('').

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

  • Si arg_type_list est une chaîne vide (''), cela indique que la fonction ne possède 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 UDTF.

• type : représente le type de données de la valeur de retour. Une UDAF renvoie une seule colonne. Les types de données pris en charge incluent 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.

Après avoir développé une UDAF Python 3 en suivant le flux de développement, vous pouvez l'appeler dans une instruction SQL MaxCompute. Les méthodes d'appel sont les suivantes :

• Utiliser une UDF dans un projet MaxCompute : la méthode est similaire à celle utilisée pour les 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.

• Utiliser 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 entre projets, consultez la section Accès aux ressources entre projets basé sur les packages.

Signature de fonction

Exemple d'UDAF

from odps.udf import annotate
from odps.udf import BaseUDAF
@annotate('bigint,*->string')
class MultiColSum(BaseUDAF):
    def new_buffer(self):
        return [0]
    def iterate(self, buffer, *args):
        for arg in args:
            buffer[0] += int(arg)
    def merge(self, buffer, pbuffer):
        buffer[0] += pbuffer[0]
    def terminate(self, buffer):
        return str(buffer[0])

-- Sums multiple input parameters.
SELECT my_multi_col_sum(a,b,c,d,e) from values (1,"2","3","4","5"), (6,"7","8","9","10") t(a,b,c,d,e);
-- The return value is 55.