MaxCompute:Python 3 UDAF

Use o Guia de introdução ao MaxCompute Studio para escrever o código da função de agregação definida pelo usuário (UDAF) em Python 3. O código deve conter as seguintes informações:

• Importar módulos: Obrigatório.

  Importe pelo menos from odps.udf import annotate e from odps.udf import BaseUDAF. A instrução from odps.udf import annotate importa o módulo de assinatura de função, que permite ao MaxCompute reconhecer a assinatura de função definida no código. from odps.udf import BaseUDAF importa a classe base para UDAFs em Python. Implemente métodos como iterate, merge e terminate na classe derivada.

  Se o código da UDAF precisar referenciar recursos de arquivo ou tabela, inclua from odps.distcache import get_cache_file para recursos de arquivo ou from odps.distcache import get_cache_table para recursos de tabela.

• Assinatura de função: Obrigatório.

  O formato é @annotate(<signature>). A signature define os tipos de dados dos parâmetros de entrada e do valor de retorno da função. Para mais informações sobre assinaturas de função, consulte Assinatura de função e tipos de dados.

• Classe Python personalizada (classe derivada): Obrigatório.

  Essa classe é a unidade organizacional do código da UDAF. Ela define as variáveis e os métodos que implementam a lógica de negócio. Também é possível referenciar bibliotecas de terceiros integradas, arquivos ou recursos de tabela no código. Para mais informações, consulte Bibliotecas de terceiros ou Referenciar recursos.

• Implementar métodos da classe Python: Obrigatório.

  A implementação da classe Python inclui os seguintes métodos. Implemente os métodos conforme necessário.

  Definição do método	Descrição
  BaseUDAF.new_buffer()	Retorna um buffer para o valor intermediário da função de agregação. O buffer deve ser um objeto Marshal, como LIST ou DICT. O tamanho do buffer não deve aumentar com o volume de dados. Em casos extremos, o tamanho do buffer após a serialização do objeto não deve exceder 2 MB.
  BaseUDAF.iterate(buffer[, args, ...])	Agrega os args ao valor intermediário buffer.
  BaseUDAF.merge(buffer, pbuffer)	Mescla os valores intermediários buffer e pbuffer e armazena o resultado em buffer.
  BaseUDAF.terminate(buffer)	Converte o buffer em um tipo de dados primitivo do MaxCompute SQL.

O código a seguir apresenta um exemplo de 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]

A figura a seguir mostra a lógica de implementação e o fluxo de cálculo de uma UDAF do MaxCompute para calcular o valor médio (

avg

).

pbuffer

corresponde a

pr

na figura, e

buffer

corresponde a

r

.

A Python Software Foundation encerrará em breve a manutenção do Python 2. Recomendamos migrar os projetos de acordo com o tipo:

• Novos projetos: Aplica-se a novos projetos do MaxCompute ou projetos do MaxCompute nos quais você está escrevendo uma UDAF em Python pela primeira vez. Recomendamos escrever todas as UDAFs em Python 3.

• Projetos existentes: Aplica-se a projetos do MaxCompute que possuem muitas UDAFs em Python 2. Ative o Python 3 com cautela. Se planeja migrar gradualmente todas as UDAFs do Python 2 para o Python 3, use os seguintes métodos:

  • Novos jobs e novas UDAFs: Escreva-os em Python 3 e ative o Python 3 no nível da sessão. Para mais informações sobre como ativar o Python 3, consulte Ativar o Python 3.

  • UDAFs em Python 2: Reescreva as UDAFs do Python 2 para que sejam compatíveis com Python 2 e Python 3. Para mais informações sobre como reescrever o código, consulte Porting Python 2 Code to Python 3.

    Nota

    Se deseja escrever uma UDAF pública e conceder permissões para vários projetos do MaxCompute usá-la, recomendamos tornar a UDAF compatível com Python 2 e Python 3.

A assinatura de função tem o seguinte formato.

@annotate(<signature>)

signature

é uma string que identifica os tipos de dados dos parâmetros de entrada e do valor de retorno. Ao executar uma UDAF, os tipos de dados dos parâmetros de entrada e do valor de retorno devem corresponder aos tipos especificados na assinatura da função. Durante a fase de análise da consulta, o sistema valida a chamada da função em relação à assinatura. Se houver incompatibilidade de tipo, um erro será reportado. O formato específico é o seguinte.

'arg_type_list -> type'

onde:

• arg_type_list: Representa os tipos de dados dos parâmetros de entrada. É possível especificar vários parâmetros de entrada, separados por vírgulas (,). Os tipos de dados suportados são 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 mais informações sobre a sintaxe estendida da anotação Resolve, consulte Parâmetros dinâmicos para UDAFs e UDTFs.

• type: Representa o tipo de dado do valor de retorno. Uma UDAF retorna apenas uma coluna. 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.

Após desenvolver uma UDAF em Python 3 seguindo o fluxo de desenvolvimento, chame-a em uma instrução SQL do MaxCompute. Os métodos de chamada são os seguintes:

• Usar uma UDF em um projeto do MaxCompute: O método é semelhante ao uso de funções integradas. Use uma função definida pelo usuário da mesma forma que usa uma função integrada.

• Usar uma UDF entre projetos: Use uma UDF do Projeto B no Projeto A. A instrução a seguir mostra um exemplo: select B:udf_in_other_project(arg0, arg1) as res from table_t;. Para mais informações sobre compartilhamento entre projetos, consulte Acesso a recursos entre projetos com base em pacotes.

Assinatura de função

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