MaxCompute:UDTF de Java

Puede escribir código de UDTF en Java mediante IntelliJ IDEA (Maven) o MaxCompute Studio. El código debe incluir los siguientes componentes:

• Paquete de Java: opcional.

  Puede organizar sus clases de Java en un paquete para facilitar su búsqueda y uso.

• Extender la clase UDTF: obligatorio.

  Las clases requeridas son com.aliyun.odps.udf.UDTF, com.aliyun.odps.udf.annotation.Resolve (para la anotación @Resolve) y com.aliyun.odps.udf.UDFException (para los métodos en la clase de Java). Si necesita usar otras clases UDTF o tipos de datos complejos, agregue las clases necesarias según MaxCompute UDF overview.

• Clase de Java personalizada: obligatoria.

  Esta es la unidad organizativa del código de la UDTF. Define las variables y los métodos que implementan su lógica de negocio.

• Anotación @Resolve: obligatoria.

  El formato es @Resolve(<signature>). signature es una firma de función que define los tipos de datos de los parámetros de entrada y del valor de retorno. Una UDTF no puede obtener la firma de la función mediante reflexión y debe usar la anotación @Resolve para especificarla; por ejemplo, @Resolve("smallint->varchar(10)"). Para obtener más información sobre la anotación @Resolve, consulte @Resolve annotation.

• Implementar métodos en la clase de Java: obligatorio.

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

  API	Descripción
  public void setup(ExecutionContext ctx) throws UDFException	Método de inicialización. MaxCompute invoca su lógica de inicialización personalizada antes de que la UDTF comience a procesar los datos de entrada. El método setup se llama una vez por cada worker.
  public void process(Object[] args) throws UDFException	La función process se invoca una vez por cada registro en una consulta SQL. Los parámetros de la función process son los parámetros de entrada especificados para la UDTF en la instrucción SQL. Los parámetros de entrada se pasan como una matriz Object[], y la salida se genera mediante la función forward. Debe llamar a la función forward dentro de la función process para determinar la salida. Nota Si no se llama a forward desde el método process o close, se pueden perder datos. Por ejemplo, si un hilo en segundo plano ejecuta una llamada a forward, debe asegurarse de que el método process no finalice hasta que la llamada a forward se complete, a fin de evitar la pérdida de datos.
  public void close() throws UDFException	Método de finalización de la UDTF. Se invoca solo una vez, después de procesar el último registro.
  public void forward(Object …o) throws UDFException	Llame al método forward para generar datos de salida; cada llamada a forward produce un registro. Cuando invoca una UDTF en una consulta SQL, puede usar la cláusula as para cambiar el nombre de la salida de forward.

  Al escribir una UDTF de Java, puede usar tipos de Java o tipos Writable de Java. Para consultar la asignación detallada entre los tipos de datos compatibles con MaxCompute y los tipos de datos de Java, consulte Data types.

// 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);
       }
     }
   }

Al escribir una UDTF de Java, tenga en cuenta lo siguiente:

• Evite definir clases con el mismo nombre pero diferente lógica de implementación en distintos paquetes JAR de UDTF. Por ejemplo, suponga que UDTF1 y UDTF2 corresponden a los recursos de paquetes JAR udtf1.jar y udtf2.jar, respectivamente. Si ambos paquetes JAR contienen una clase llamada com.aliyun.UserFunction.class con lógicas diferentes, MaxCompute cargará aleatoriamente una de las clases cuando se invoquen UDTF1 y UDTF2 en la misma instrucción SQL. Esto puede provocar resultados inesperados o fallos de compilación.

• Los parámetros de entrada y los valores de retorno deben usar tipos de objeto de Java, como String y Long, en lugar de tipos primitivos.

• Esto se debe a que los valores NULL de SQL se pasan como null de Java, lo cual no puede representarse con tipos primitivos.

El formato de la anotación @Resolve es el siguiente.

@Resolve(<signature>)

La cadena signature especifica los tipos de datos de los parámetros de entrada y los valores de retorno de la UDTF. Durante el análisis de la consulta, MaxCompute valida las invocaciones con base en esta firma y reporta un error si detecta una discrepancia de tipos. El formato es el siguiente.

'arg_type_list -> type_list'

Donde:

• type_list: representa los tipos de datos de los valores de retorno. Una UDTF puede devolver varias columnas. Los tipos de datos compatibles son 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.

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

  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.

Después de desarrollar una UDTF de Java siguiendo development process, puede invocarla en MaxCompute SQL.

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

• Usar una UDF entre proyectos: utilice una UDF del Proyecto B en el Proyecto A. La siguiente instrucción muestra un ejemplo: select B:udf_in_other_project(arg0, arg1) as res from table_t;. Para obtener más información sobre el uso compartido entre proyectos, consulte Cross-project resource access based on packages.