# signature说明
signature用于描述UDF的函数签名，即函数的输入参数和返回值的类型信息。它由Parameter 列表 + return_annotation组成，注册函数时被写入LakeFormation元数据，供引擎调用时进行参数与类型的匹配。
#### signature参数说明
signature对象由Parameter列表与return_annotation组成。
表1属性说明 
| 属性        | 类型            | 说明                                                                                    |
|:---|:---|:---|
| 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__。 |
| 绑定方法      | 自动解包为普通函数推断。                                                            |
   
![](https://support.huaweicloud.com/sdkreference-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
- 所有参数必须带类型注解；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         |
   
![](https://support.huaweicloud.com/sdkreference-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
- 若signature由注解自动推断且参数为非批量元素类型，SDK抛ValueError。
- 若显式传入signature使用元素类型，SDK会改从UDF自身注解推断input_type。
- 建议使用 list\[T\] 携带元素类型信息，便于LakeFormation存储列原始数据类型；裸pyarrow.Array、pandas.Series不携带元素类型时会在from_signature阶段报错。