MaxCompute:Desenvolvimento de UDFs em Java

Ao escrever uma UDF em Java, observe os seguintes pontos:

• Evite incluir classes com o mesmo nome, mas com lógicas diferentes, em arquivos JAR de UDF distintos. Por exemplo, se UDF1 e UDF2 corresponderem a udf1.jar e udf2.jar, respectivamente, e ambos os arquivos JAR contiverem com.aliyun.UserFunction.class com lógicas diferentes, chamar ambas as UDFs na mesma instrução SQL fará com que o MaxCompute carregue aleatoriamente uma das classes. Isso pode levar a resultados inesperados ou a uma falha de compilação.

• Em uma UDF Java, os parâmetros de entrada e os valores de retorno devem usar tipos de objeto (como String e Long), e não tipos primitivos (como int e long).

• Os valores NULL em SQL são mapeados para NULL em Java. Os tipos primitivos do Java não podem representar valores NULL e, portanto, não são permitidos.

Após desenvolver uma UDF Java conforme descrito em UDF development workflow, chame-a no MaxCompute SQL. Os seguintes métodos estão disponíveis:

• Uso de uma UDF em um projeto do MaxCompute: o método é semelhante ao uso de built-in functions. Use uma função definida pelo usuário da mesma forma que usa uma função integrada.

• Uso de uma UDF entre projetos: use 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 mais informações sobre o compartilhamento entre projetos, consulte Cross-project resource access based on packages.

• Write a Hive UDF in Java

• Use complex data types in Java UDFs

• Replace strings by using regular expressions

• Obtain the values of strings that have no delimiters

• Obtain the values of strings that have delimiters

• Reference a file resource

• Reference a table resource

• Reference third-party packages in Python UDFs

Uma UDF Java consiste nas seguintes partes:

• Pacote Java: opcional.

  Agrupe suas classes Java em um pacote para facilitar a reutilização e a organização.

• Herança da classe UDF: obrigatória.

  A classe base obrigatória é com.aliyun.odps.udf.UDF. Caso precise de outras classes UDF ou tipos de dados complexos, adicione as classes necessárias de MaxCompute SDK. Por exemplo, a classe para o tipo de dados STRUCT é com.aliyun.odps.data.Struct.

• Anotação @Resolve: opcional.

  O formato é @Resolve(<signature>), em que signature define os tipos de dados dos parâmetros de entrada e do valor de retorno. Ao usar o tipo de dados STRUCT em uma UDF, a reflexão não consegue recuperar os nomes e os tipos dos campos de com.aliyun.odps.data.Struct. Nesse caso, use a anotação @Resolve para recuperá-los. Se usar STRUCT em uma UDF, adicione a anotação @Resolve à classe da UDF. A anotação afeta apenas as sobrecargas cujos parâmetros ou valores de retorno contêm com.aliyun.odps.data.Struct. Exemplo: @Resolve("struct<a:string>,string->string"). Para um exemplo detalhado, consulte UDF Example: Complex Data Types.

• Classe Java personalizada: obrigatória.

  Esta é a unidade que organiza o código da sua UDF e define as variáveis e os métodos que implementam a lógica do seu negócio.

• Método evaluate: obrigatório.

  Sua classe Java personalizada deve incluir um método evaluate público e não estático. Os tipos de dados de seus parâmetros de entrada e valor de retorno definem a assinatura SQL da UDF.

  Implemente vários métodos evaluate. Ao chamar a UDF, o MaxCompute seleciona o método evaluate correspondente com base nos tipos de argumento.

  Ao escrever uma UDF Java, use tipos Java ou tipos Java Writable. Para mapeamentos detalhados entre os tipos de dados do MaxCompute e os tipos de dados Java, consulte Appendix: Data types.

• Inicialização e limpeza da UDF: opcional. Implemente a inicialização e a limpeza usando void setup(ExecutionContext ctx) e void close(). O método void setup(ExecutionContext ctx) é chamado uma vez antes do método evaluate e pode ser usado para inicializar recursos ou objetos membro necessários para a computação. O método void close() é chamado uma vez após a conclusão de todas as chamadas evaluate e é usado para tarefas de limpeza, como o fechamento de arquivos.

Os exemplos a seguir mostram dois tipos de UDFs.

• Uso de tipos 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(); 
    } 
  }

• Uso de tipos 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;
    }
  }

Mapeamentos de tipos de dados

Para garantir que os tipos de dados usados em uma UDF Java sejam consistentes com os tipos de dados do MaxCompute, use os seguintes mapeamentos.

O tipo Java byte[] não está na lista de tipos Java suportados. Caso use byte[] para um parâmetro de entrada ou para o valor de retorno de um método evaluate, o sistema relatará o erro ODPS-0130071. Para processar dados binários em uma UDF, use os tipos Java correspondentes ao tipo BINARY do MaxCompute: com.aliyun.odps.data.Binary para o tipo Java padrão ou com.aliyun.odps.io.BytesWritable para o tipo Writable. Também é possível converter dados binários em uma string codificada em Base64 e usar o tipo String para o valor de retorno.

Compatibilidade com UDFs do Hive

Se o seu projeto do MaxCompute usar a edição de tipos de dados 2.0, o MaxCompute oferecerá suporte a UDFs no estilo do Hive. Use diretamente as UDFs do Hive desenvolvidas para uma versão compatível do Hive.

A versão compatível do Hive é a 2.1.0, que corresponde ao Hadoop 2.7.2. Caso sua UDF tenha sido compilada em uma versão diferente do Hive ou do Hadoop, recompile o arquivo JAR da UDF com o Hive 2.1.0 ou o Hadoop 2.7.2.

Para um exemplo detalhado de uso de uma UDF do Hive no MaxCompute, consulte UDF Example: Hive Compatibility.