MaxCompute:UDAF de Python 3

Con Get started with MaxCompute Studio puede escribir el código de una función de agregación definida por el usuario (UDAF) en Python 3. El código debe contener la siguiente información:

• Importar módulos: obligatorio.

  Como mínimo, debe importar from odps.udf import annotate y from odps.udf import BaseUDAF. La instrucción from odps.udf import annotate importa el módulo de firma de función, lo que permite que MaxCompute reconozca la firma definida en el código. Por su parte, from odps.udf import BaseUDAF importa la clase base para las UDAF de Python. En la clase derivada debe implementar métodos como iterate, merge y terminate.

  Si el código de la UDAF necesita hacer referencia a recursos de archivo o de tabla, incluya from odps.distcache import get_cache_file para los recursos de archivo o from odps.distcache import get_cache_table para los recursos de tabla.

• Firma de función: obligatorio.

  El formato es @annotate(<signature>). El elemento signature define los tipos de datos de los parámetros de entrada y del valor de retorno de la función. Para obtener más información sobre las firmas de función, consulte Function signature and data types.

• Clase de Python personalizada (clase derivada): obligatorio.

  Esta clase es la unidad organizativa del código de la UDAF. Define las variables y los métodos que implementan su lógica de negocio. También puede hacer referencia a bibliotecas de terceros integradas, archivos o recursos de tabla en el código. Para obtener más información, consulte Third-party libraries o Reference resources.

• Implementar los métodos de la clase de Python: obligatorio.

  La implementación de la clase de Python incluye los siguientes métodos. Puede implementarlos según sus necesidades.

  Definición del método	Descripción
  BaseUDAF.new_buffer()	Devuelve un búfer para el valor intermedio de la función de agregación. El elemento buffer debe ser un objeto Marshal, como LIST o DICT. El tamaño del elemento buffer no debe aumentar conforme crece el volumen de datos. En casos extremos, el tamaño del elemento buffer después de serializar el objeto no debe superar los 2 MB.
  BaseUDAF.iterate(buffer[, args, ...])	Agrega los elementos args en el valor intermedio buffer.
  BaseUDAF.merge(buffer, pbuffer)	Combina los valores intermedios buffer y pbuffer, y almacena el resultado en buffer.
  BaseUDAF.terminate(buffer)	Convierte el elemento buffer a un tipo de datos primitivo de MaxCompute SQL.

A continuación se muestra un ejemplo de código de una 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 siguiente imagen muestra la lógica de implementación y el flujo de cálculo de una UDAF de MaxCompute diseñada para calcular el valor promedio (

avg

).

El elemento

pbuffer

corresponde a

pr

en la imagen, mientras que

buffer

corresponde a

r

.

La Python Software Foundation dejará de dar mantenimiento a Python 2 pronto. Se recomienda migrar los proyectos según su tipo:

• Proyectos nuevos: aplica a proyectos de MaxCompute recién creados o a aquellos donde se escribe una UDAF de Python por primera vez. Se recomienda escribir todas las UDAF de Python en Python 3.

• Proyectos existentes: aplica a proyectos de MaxCompute que ya cuentan con varias UDAF de Python 2. Habilite Python 3 con precaución. Si planea migrar gradualmente todas las UDAF de Python 2 a Python 3, utilice los siguientes métodos:

  • Trabajos y UDAF nuevas: escríbalos en Python 3 y habilite Python 3 a nivel de sesión. Para obtener más información sobre cómo habilitar Python 3, consulte Enable Python 3.

  • UDAF de Python 2: reescriba las UDAF de Python 2 para que sean compatibles tanto con Python 2 como con Python 3. Para obtener más información sobre cómo reescribir el código, consulte Porting Python 2 Code to Python 3.

    Nota

    Si desea escribir una UDAF pública y otorgar permisos para que varios proyectos de MaxCompute la utilicen, se recomienda hacerla compatible tanto con Python 2 como con Python 3.

set odps.sql.python.version=cp37;

La firma de función tiene el siguiente formato.

@annotate(<signature>)

El elemento

signature

es una cadena que identifica los tipos de datos de los parámetros de entrada y del valor de retorno. Al ejecutar una UDAF, los tipos de datos de sus parámetros de entrada y de su valor de retorno deben coincidir con los especificados en la firma de función. Durante la fase de análisis sintáctico de la consulta, el sistema valida la llamada a la función con base en dicha firma. Si detecta una discrepancia de tipos, reporta un error. El formato específico es el siguiente.

'arg_type_list -> type'

donde:

• arg_type_list: representa los tipos de datos de los parámetros de entrada. Se pueden especificar varios parámetros de entrada separados por comas (,). Los tipos de datos compatibles son BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(precision,scale), CHAR, VARCHAR, tipos de datos complejos (ARRAY, MAP, STRUCT) y tipos de datos complejos anidados.

  El elemento arg_type_list también admite un asterisco (*) o una cadena vacía ('').

  • Si arg_type_list es un asterisco (*), indica que la función acepta cualquier cantidad de parámetros de entrada.

  • Si arg_type_list es una cadena vacía (''), indica que la función no tiene parámetros de entrada.

  Para obtener más información sobre la sintaxis extendida de la anotación Resolve, consulte Dynamic parameters for UDAFs and UDTFs.

• type: representa el tipo de datos del valor de retorno. Una UDAF devuelve solo una columna. Los tipos de datos compatibles incluyen BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(precision,scale), tipos de datos complejos (ARRAY, MAP, STRUCT) y tipos de datos complejos anidados.

Una vez que desarrolle una UDAF de Python 3 siguiendo el development flow, podrá llamarla en una instrucción de MaxCompute SQL. A continuación se describen los métodos de llamada:

• Usar una UDF dentro de un proyecto de MaxCompute: este método es similar al de usar built-in functions. Puede utilizar una función definida por el usuario de la misma manera que una función integrada.

• Usar una UDF entre proyectos: consiste en utilizar una UDF del Proyecto B dentro del Proyecto A. En la siguiente instrucción se muestra un ejemplo: select B:udf_in_other_project(arg0, arg1) as res from table_t;. Para obtener más información sobre cómo compartir recursos entre proyectos, consulte Cross-project resource access based on packages.

Firma de función

Ejemplo de 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.