MaxCompute:UDTF em Java

É possível escrever o código da UDTF em Java usando o IntelliJ IDEA (Maven) ou MaxCompute Studio. O código deve incluir os seguintes componentes:

• Pacote Java: Opcional.

  Organize suas classes Java em um pacote para facilitar a localização e o uso.

• Estender a classe UDTF: Obrigatório.

  As classes necessárias são com.aliyun.odps.udf.UDTF, com.aliyun.odps.udf.annotation.Resolve (para a anotação @Resolve) e com.aliyun.odps.udf.UDFException (para métodos na classe Java). Caso precise utilizar outras classes UDTF ou tipos de dados complexos, adicione as classes necessárias conforme MaxCompute UDF overview.

• Classe Java personalizada: Obrigatório.

  Esta é a unidade organizacional do código da UDTF. Ela define as variáveis e os métodos que implementam sua lógica de negócios.

• Anotação @Resolve: Obrigatório.

  O formato é @Resolve(<signature>). signature é uma assinatura de função que define os tipos de dados dos parâmetros de entrada e do valor de retorno. Uma UDTF não consegue obter a assinatura da função por reflexão e deve usar a anotação @Resolve para especificá-la, por exemplo, @Resolve("smallint->varchar(10)"). Para obter mais informações sobre a anotação @Resolve, consulte @Resolve annotation.

• Implementar métodos na classe Java: Obrigatório.

  A implementação da classe Java inclui os quatro métodos a seguir. Escolha implementá-los conforme suas necessidades.

  API	Descrição
  public void setup(ExecutionContext ctx) throws UDFException	Método de inicialização. O MaxCompute chama sua lógica de inicialização personalizada antes que a UDTF comece a processar os dados de entrada. O método setup é chamado uma vez por worker.
  public void process(Object[] args) throws UDFException	A função process é chamada uma vez para cada registro em uma consulta SQL. Os parâmetros da função process correspondem aos parâmetros de entrada especificados para a UDTF na instrução SQL. Esses parâmetros são passados como um array Object[], e a saída é gerada por meio da função forward. É obrigatório chamar a função forward dentro da função process para determinar a saída. Nota Deixar de chamar forward no método process ou close pode causar perda de dados. Por exemplo, se uma thread em segundo plano executar uma chamada forward, garanta que o método process não termine até que a chamada forward seja concluída, evitando assim a perda de dados.
  public void close() throws UDFException	Método de encerramento da UDTF. Ele é chamado apenas uma vez, após o processamento do último registro.
  public void forward(Object …o) throws UDFException	Chame o método forward para gerar dados de saída; cada chamada a forward produz um registro. Ao chamar uma UDTF em uma consulta SQL, utilize a cláusula as para renomear a saída de forward.

  Ao escrever uma UDTF em Java, utilize Java Type ou Java Writable Type. Para obter o mapeamento detalhado entre os tipos de dados suportados pelo MaxCompute e os tipos de dados 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);
       }
     }
   }

Ao escrever uma UDTF em Java, observe os pontos a seguir:

• Evite definir classes com o mesmo nome, mas com lógicas de implementação diferentes, em pacotes JAR de UDTF distintos. Por exemplo, suponha que UDTF1 e UDTF2 correspondam aos recursos de pacote JAR udtf1.jar e udtf2.jar, respectivamente. Se ambos os pacotes JAR contiverem uma classe chamada com.aliyun.UserFunction.class com lógicas diferentes, o MaxCompute carregará aleatoriamente uma das classes quando UDTF1 e UDTF2 forem chamadas na mesma instrução SQL. Isso pode causar resultados inesperados ou falhas de compilação.

• Os parâmetros de entrada e os valores de retorno devem usar tipos de objeto Java, como String e Long, em vez de tipos primitivos.

• Isso ocorre porque valores SQL NULL são passados como null em Java, o que tipos primitivos não conseguem representar.

O formato da anotação @Resolve é o seguinte:

@Resolve(<signature>)

A string signature especifica os tipos de dados dos parâmetros de entrada e dos valores de retorno da UDTF. Durante a análise da consulta, o MaxCompute valida as chamadas com base nessa assinatura e relata um erro caso encontre incompatibilidade de tipos. O formato é o seguinte:

'arg_type_list -> type_list'

Onde:

• type_list: Representa os tipos de dados dos valores de retorno. Uma UDTF pode retornar várias colunas. Os tipos de dados suportados incluem BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(precision,scale), tipos de dados complexos (ARRAY, MAP, STRUCT) e tipos de dados complexos aninhados.

• arg_type_list: Representa os tipos de dados dos parâmetros de entrada. É possível especificar múltiplos parâmetros de entrada, separados por vírgulas (,). Os tipos de dados suportados incluem BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(precision,scale), CHAR, VARCHAR, tipos de dados complexos (ARRAY, MAP, STRUCT) e tipos de dados complexos aninhados.

  arg_type_list também aceita um asterisco (*) ou uma string vazia ('').

  • Se arg_type_list for um asterisco (*), indica que a função aceita qualquer número de parâmetros de entrada.

  • Se arg_type_list for uma string vazia (''), indica que a função não possui parâmetros de entrada.

  Para obter mais informações sobre a sintaxe estendida da anotação Resolve, consulte Dynamic parameters for UDAFs and UDTFs.

Após desenvolver uma UDTF em Java seguindo as instruções em development process, chame-a no MaxCompute SQL.

• Usar uma UDF em um projeto MaxCompute: O método é semelhante ao uso de built-in functions. Utilize uma função definida pelo usuário da mesma maneira que uma função integrada.

• Usar uma UDF entre projetos: Utilize uma UDF do Projeto B no Projeto A. A seguinte instrução mostra um exemplo: select B:udf_in_other_project(arg0, arg1) as res from table_t;. Para obter mais informações sobre compartilhamento entre projetos, consulte Cross-project resource access based on packages.