signature说明
signature用于描述UDF的函数签名，即函数的输入参数和返回值的类型信息。它由Parameter 列表 + return_annotation组成，注册函数时被写入LakeFormation元数据，供引擎调用时进行参数与类型的匹配。
signature参数说明
signature对象由Parameter列表与return_annotation组成。
| 属性 | 类型 | 说明 |
|---|---|---|
| name | str | 参数名。 |
| kind | ParameterKind | 参数类别：POSITIONAL_ONLY/POSITIONAL_OR_KEYWORD/KEYWORD_ONLY/VAR_POSITIONAL/VAR_KEYWORD。 |
| default | Any | 默认值；无默认值时为EMPTY。 |
| annotation | Any | 类型注解；无注解时为EMPTY。 |
什么情况下使用
| 场景 | 推荐做法 |
|---|---|
| UDF有完整、准确的类型注解 | 传signature=None，交由SDK自动推断。 |
| UDF注解与实际期望签名不一致，或需覆盖 | 显式传入Signature对象。 |
| 批量模式下需要使用元素类型作为签名 | 显式传入带元素类型的Signature，SDK据此映射Lakeformation列类型。 |
自动推断规则（signature=None时）
当signature未显式传入（为 None）时，SDK依据UDF的代码形态与类型注解自动推断函数签名，无需手动构造Signature对象。推断失败时抛出SignatureInferenceError。
语法示例：
为UDF标注参数与返回值的类型注解，即可触发自动推断。
# 带类型注解的 UDF（推荐写法）
def to_celsius(fahrenheit: float) -> float:
return (fahrenheit - 32) * 5 / 9
# signature=None 时，SDK 自动推断出等价签名：
# signature = [Parameter(name="fahrenheit", kind=POSITIONAL_OR_KEYWORD, default=EMPTY, annotation=float)]
# return_annotation = float
client.create_udf(to_celsius, name="to_celsius") 推断规则:
| UDF 形式 | 推断行为 |
|---|---|
| 普通函数 | 使用inspect.signature + get_type_hints读取参数与返回注解。 |
| 类定义形式UDF | 检查类中的__call__方法，读取其注解；若类无自定义__call__，抛出SignatureInferenceError。 |
| 类实例形式UDF | 检查实例所属类的__call__方法；实例本身已通过cloudpickle序列化，class_name取自 type(udf).__name__。 |
| 绑定方法 | 自动解包为普通函数推断。 |
- 所有参数必须带类型注解；FunctionSignature.from_signature 会对无注解参数抛出ValueError。
- 裸容器类型（如list、dict而无元素类型）不被接受，须使用 list[T]、dict[K, V]等带元素类型的注解。
- 若signature为None且推断失败（例如函数无类型注解、类无 __call__），SDK会抛出SignatureInferenceError。
批量模式（is_batch=True）下的signature要求
批量模式（is_batch=True）下，UDF一次性处理一批数据而非单行数据，因此signature的参数注解必须使用批量类型（pyarrow或pandas的数组/表结构），且所有参数的批量类型必须一致，以匹配引擎的批量传参方式。
语法示例
使用批量类型注解定义批量UDF，并注册时开启 is_batch。
import pyarrow as pa
def double_batch(values: pa.Array) -> pa.Array:
return pa.array([v * 2 for v in values])
client.create_udf(double_batch, name="double_batch", is_batch=True, batch_size=1024) 批量类型对照
| 批量类型 | 检测到的input_type |
|---|---|
| pyarrow.Array/pyarrow.Table | pyarrow |
| pandas.Series/pandas.DataFrame | pandas |
- 若signature由注解自动推断且参数为非批量元素类型，SDK抛ValueError。
- 若显式传入signature使用元素类型，SDK会改从UDF自身注解推断input_type。
- 建议使用 list[T] 携带元素类型信息，便于LakeFormation存储列原始数据类型；裸pyarrow.Array、pandas.Series不携带元素类型时会在from_signature阶段报错。
