MaxCompute：Python 2 UDTF

• 編碼聲明：可選。

  固定聲明格式為#coding:utf-8或# -*- coding: utf-8 -*-，二者等效。當Python 2代碼中出現中文字元時，運行程式會報錯，您需要在代碼頭部增加編碼聲明。

• 匯入模組：必選。

  至少要包含from odps.udf import annotate和from odps.udf import BaseUDTF。from odps.udf import annotate用於匯入函數簽名模組，MaxCompute才可以識別後續代碼中定義的函數簽名。from odps.udf import BaseUDTF為Python UDTF的基類，您需要通過此類在衍生類別中實現process或close等方法。

  當UDTF代碼中需要引用檔案資源或表資源時，需要包含from odps.distcache import get_cache_file（檔案資源）或from odps.distcache import get_cache_table（表資源）。

• 函數簽名：可選。

  格式為@annotate(<signature>)，signature用於定義函數的輸入參數和傳回值的資料類型。如果不指定函數簽名，在SQL中調用UDTF時，可以匹配任意類型的輸入參數，但傳回值類型無法推導，所有輸出參數都將會是STRING類型。更多函數簽名資訊，請參見函數簽名及資料類型。

• 自訂Python類（衍生類別）：必選。

  UDTF代碼的組織單位，定義了實現業務需求的變數及方法。您還可以在代碼中引用MaxCompute內建的第三方庫或引用檔案、表資源。更多資訊，請參見第三方庫或引用資源。

• 實現Python類的方法：必選。

  Python類實現包含如下4個方法，您可以根據實際需要進行選擇。

  方法定義	描述
  BaseUDTF.init()	初始化方法。衍生類別如果需要實現此方法，必須在一開始調用基類的初始化方法super(BaseUDTF, self).init()。init方法在整個UDTF生命週期中只會被調用一次，即在處理第一條記錄之前。當UDTF需要儲存內部狀態時，可以通過此方法初始化所有狀態。
  BaseUDTF.process([args, ...])	SQL中每一條記錄都會對應調用一次process，process的參數為SQL語句中指定的UDTF輸入參數。
  BaseUDTF.forward([args, ...])	UDTF的輸出方法。此方法由使用者代碼調用。每調用一次forward，就會輸出一條記錄。forward的參數為SQL語句中指定的UDTF的輸出參數。 如果Python代碼中未指定函數簽名，在調用forward方法時，必須將所有輸出值轉換為STRING類型。
  BaseUDTF.close()	UDTF的結束方法。只會被調用一次，即在處理完最後一條記錄之後被調用。

#coding:utf-8
#匯入函數簽名模組及基類。
from odps.udf import annotate
from odps.udf import BaseUDTF
#函數簽名。
@annotate('string -> string')
#自訂Python類。
class Explode(BaseUDTF):
#實現Python類的方法。
   def process(self, arg):
       props = arg.split(',')
       for p in props:
           self.forward(p)

• 讀寫本地檔案。

• 啟動子進程。

• 啟動線程。

• 使用Socket通訊。

• 其他系統調用。

基於上述原因，您上傳的代碼都必須通過標準Python實現。Python標準庫中涉及到上述功能的模組或C擴充模組都會被禁止使用。具體標準庫的可用模組說明如下：

• 所有基於標準Python實現（不依賴擴充模組）的模組都可用。

• C擴充模組中下列模組可用：

  • array、audioop

  • binascii、bisect

  • cmath、_codecs_cn、_codecs_hk、_codecs_iso2022、_codecs_jp、_codecs_kr、_codecs_tw、_collections、cStringIO

  • datetime

  • _functools、future_builtins、

  • _heapq、_hashlib

  • itertools

  • _json

  • _locale、_lsprof

  • math、_md5、_multibytecodec

  • operator

  • _random

  • _sha256、_sha512、_sha、_struct、strop

  • time

  • unicodedata

  • _weakref

  • cPickle

• 沙箱限制了您的代碼最多可向標準輸出和標準錯誤輸出寫入資料的大小為20 KB，即sys.stdout/sys.stderr最多能寫入20 KB資料，多餘的字元會被忽略。

MaxCompute的Python 2運行環境中安裝了除Python標準庫外比較常用的第三方庫，作為標準庫的補充，例如Numpy。

@annotate(<signature>)

signature為函數簽名字串，用於標識輸入參數和傳回值的資料類型。執行UDTF時，UDTF函數的輸入參數和傳回值類型要與函數簽名指定的類型一致。查詢語義解析階段會檢查不符合函數簽名定義的用法，檢查到類型不符時會報錯。具體格式如下。

'arg_type_list -> type_list'

其中：

• type_list：表示傳回值的資料類型。UDTF可以返回多列。支援的資料類型為：BIGINT、STRING、DOUBLE、BOOLEAN、DATETIME、DECIMAL、FLOAT、BINARY、DATE、DECIMAL(precision,scale)、複雜資料類型（ARRAY、MAP、STRUCT）或複雜資料類型嵌套。

• arg_type_list：表示輸入參數的資料類型。輸入參數可以為多個，用英文逗號（,）分隔。支援的資料類型為BIGINT、STRING、DOUBLE、BOOLEAN、DATETIME、DECIMAL、FLOAT、BINARY、DATE、DECIMAL(precision,scale)、CHAR、VARCHAR、複雜資料類型（ARRAY、MAP、STRUCT）或複雜資料類型嵌套。

  arg_type_list還支援星號（*）或為空白（''）：

  • 當arg_type_list為星號（*）時，表示輸入參數為任意個數。

  • 當arg_type_list為空白（''）時，表示無輸入參數。

# -*- coding: utf-8 -*-
from odps.udf import annotate
from odps.udf import BaseUDTF
from odps.distcache import get_cache_file
from odps.distcache import get_cache_table
@annotate('string -> string, bigint')
class UDTFExample(BaseUDTF):
    """讀取資源檔和資源表裡的pageid、adid，產生dict
    """
    def __init__(self):
        import json
        cache_file = get_cache_file('test_json.txt')
        self.my_dict = json.load(cache_file)
        cache_file.close()
        records = list(get_cache_table('table_resource1'))
        for record in records:
            self.my_dict[record[0]] = [record[1]]
    """輸入pageid，輸出pageid以及它對應的所有adid
    """
    def process(self, pageid):
        for adid in self.my_dict[pageid]:
            self.forward(pageid, adid)

• 在歸屬MaxCompute專案中使用自訂函數：使用方法與內建函數類似，您可以參照內建函數的使用方法使用自訂函數。

• 跨專案使用自訂函數：即在專案A中使用專案B的自訂函數，跨專案分享語句樣本：select B:udf_in_other_project(arg0, arg1) as res from table_t;。更多跨專案分享資訊，請參見基於Package跨專案訪問資源。