# UDF概述 用户自定义函数（User-Defined Function，简称UDF）是指由用户根据特定需求自定义的函数，用于扩展数据库或数据处理系统的功能。UDF可以执行各种操作，如数据转换、复杂计算、数据聚合等，这些操作可能超出了系统提供的内置函数的能力。 UDF的主要用途包括： - 扩展功能：UDF允许用户扩展数据库或数据处理系统的功能，执行内置函数不支持的操作。 - 复杂计算：UDF可用于执行复杂的数学或逻辑计算，这些计算可能涉及多个步骤和条件。 - 数据转换：UDF可用于数据清洗和转换，如格式化日期、转换字符串或编码数据。 - 业务逻辑封装：UDF可将业务逻辑封装在函数中，使得数据处理更加模块化和可重用。 - 性能优化：在某些情况下，通过UDF将复杂的计算逻辑移到数据库服务器上执行，可以减少数据传输和提高性能。 ![](https://support.huaweicloud.com/sqlref-aura-aidatalake/public_sys-resources/note_3.0-zh-cn.png) 在大数据处理中，如果需要在DataFrame上执行自定义函数UDF来处理复杂逻辑或调用第三方库，但执行UDF的容器或集群只预装了基础Python库，您可以在UDF中使用pip install package命令安装最新版本的依赖，从而灵活使用各种Python库。如果您需要安装指定版本的依赖，需加具体版本号，示例命令为pip install pandas==2.2.2。 #### 约束限制 - UDF编程语言仅支持Python。 - UDF的参数不支持设置默认值，如果创建函数时参数或返回值带有精度，不进行精度检测。 - 不支持函数重载。 #### UDF类型 在Aura DataFrame SDK中支持了Scalar UDF、Class UDF、Vectorized UDF、UDTF、UDAF等不同类别UDF的注册和使用。 表1UDF类型介绍 | 类型 | 输入 | 输出 | 描述 | |:---|:---|:---|:---| | Scalar UDF（标量UDF） | 单行输入，多参数，例如(a, b, c) | 单行输出，一个标量，例如int/float/string/date | 最常见形式，每次被调用时只处理一行数据。可以做简单计算、格式化、清洗、转换。例如：字符串清洗、数学计算、日期转换。类比Python的普通函数。 | | Class UDF（类UDF） | 与Scalar UDF相同：单行输入 | 单行输出 | 是对Scalar UDF的OOP封装方式，适合有内部缓存、初始化参数、模型对象等情况。例如需要在函数内部加载一次模型、正则、配置。数据库只是在内部初始化一次，不需要每次调用都构建资源。 | | Vectorized UDF（向量化UDF） | 一次性输入一批行，类型为pandas.Series/pyarrow.ChunkedArray | 一次性输出同等数量行的向量化结构 | 性能最优的单行转换方式，用于批量处理。适合：向量化数学计算、文本批量处理、embedding处理、NLP分词。具有SIMD/批量执行优势，常用于Arrow、Pandas。 | | UDTF（User Defined Table Function，表函数） | 单行输入 | 多行输出 | 一个输入可能产出多个输出行。类似Python的yield。用于拆分、展开、解包结构化数据。例如：拆分JSON数组、展开多模态数据、音频/视频分片、tokenize、爆炸式展开。 | | UDAF（User Defined Aggregate Function，聚合函数） | 多行输入，可能来自多个分区 | 单个输出 | 对一组数据做聚合的函数：累加、统计、聚类、embedding聚合。具备accumulate、merge、finish生命周期，支持分布式执行。 | #### UDF注册方式 注册UDF总体上来说分为两种方式：显式注册和隐式注册。 表2注册UDF方式 | 注册方式 | 含义 | 是否依赖会话对象 | 是否侵入式添加注册逻辑 | 适用场景 | 参考 | |:---|:---|:---|:---|:---|:---| | 显式注册 | 代码中明确指定UDF的注册信息 | 是 | 是 | 如果用户希望明确控制注册时间，允许侵入式添加注册逻辑，或对同一个Backend连接下的Scalar UDF注册和使用分离有要求。 | [UDF显式注册语法](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0134.html#aidatalake_061_0134__zh-cn_topic_0000002530001164_section644865765810) | | 隐式注册 | 运行时自动发现并注册UDF | 否 | 否 | 如果用户希望无侵入式地注册Scalar UDF，且对同一个Backend连接下的Scalar UDF注册和使用分离无要求。 | [UDF隐式注册语法](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0134.html#aidatalake_061_0134__zh-cn_topic_0000002530001164_section1531011357119) | #### UDF注册类型 不管是显式注册还是隐式注册，对于不同的UDF注册类型，其含义有所不同，详情参见下表： 表3UDF注册类型的含义 | UDF注册类型 | 含义 | 是否向量化 | 适用场景与特点 | 参考 | |:---|:---|:---|:---|:---| | Python | 将一个原始的Python函数或者类注册进数据库中。 | 否 | 逐行处理数据，适用于简单或特定的计算，但性能较低。 | [Python/Pyarrow/Pandas UDF注册参数](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0134.html#aidatalake_061_0134__zh-cn_topic_0000002530001164_section1284915118269) | | Builtin | 获得数据库已存在的函数的句柄，无实际注册的操作。 | 否 | 直接调用数据库后端已存在的函数，适用于利用数据库原生功能的场景。 | [Builtin UDF注册参数](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0134.html#aidatalake_061_0134__zh-cn_topic_0000002530001164_section196511519183118) | | PyArrow | 将一个接受pyarrow.ChunkedArray作为输入和输出的Python函数或类注册进数据库中。 | 是 | 利用PyArrow的高性能计算能力，适用于需要处理大型数据集或进行高效计算的场景。 | [Python/Pyarrow/Pandas UDF注册参数](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0134.html#aidatalake_061_0134__zh-cn_topic_0000002530001164_section1284915118269) | | Pandas | 将一个接受pandas.Series作为输入和输出的Python函数或类注册进数据库中。 | 是 | 利用Pandas的矢量化操作，适用于需要在Python层进行复杂数据处理的场景。 | [Python/Pyarrow/Pandas UDF注册参数](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0134.html#aidatalake_061_0134__zh-cn_topic_0000002530001164_section1284915118269) | 对于Scalar UDF，目前支持全部上述4种注册类型。 对于UDAF、UDTF，目前仅支持上述的python、builtin这2种注册类型。 #### UDF运行时的额外参数 不管是显式注册还是隐式注册，对于所有的UDF类型，都支持在使用时通过with_arguments方法传入额外参数。这些参数包括了concurrency、min_concurrency、max_concurrency、timeout、dpu、apu，可以为UDF的执行提供细粒度的资源分配、并发度控制、时间上限等。 具体用法见[UDF WITH ARGUMENTS使用语法](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0134.html#aidatalake_061_0134__zh-cn_topic_0000002530001164_section1727318557443)。