Function API

DuckDB 提供了Function API 来为 DuckDB 中引入用户自定义函数(UDF)。这些 UDF 能够在 SQL 查询中使用:

Python

def DuckDBPyConnection.create_function(
  name:str,                                 # 要在查询语句中使用的函数名
  func: Callable,                           # Python 方法
  args: Optional[List[DuckDBPyType]],       # 函数签名列表，例如 [INTEGER, BOOL] 其中的类型是 DuckDBPyType
  return_type: Optional[DuckDBPyType],      # 函数返回值类型
  vectorized: Optional[bool] = False,       #
  null_handling = FunctionNullHandling.DEFAULT,          # null 值处理
  exception_handling = PythonExceptionHandling.DEFAULT,  # 异常处理
  side_effects: Optional[bool] = False                   # 副作用处理
)  -> DuckDBPyConnection:
    pass

这里面比较不好理解的就是两个 handling 参数:

• null_handling: 默认情况下，当过程函数收到一个 NULL 值是，会立即返回 NULL(不会经过函数处理)。如果不需要这样处理，即 NULL 也要经过过程函数可以设置null_handling="special"
• exception_handling: 默认情况下，当过程函数引发异常时异常被抛出，如果希望实现异常直接返回 NULL 则可以设置exception_handling="return_null"

类型注解

当函数包含类型注解时，通常可以省略所有可选参数。这也是最推荐的实现方式:

Python

import duckdb


def my_function(x: int) -> str:
    return x


duckdb.create_function("my_func", my_function)
print(duckdb.sql("SELECT my_func(42)"))

    ┌─────────────┐
    │ my_func(42) │
    │   varchar   │
    ├─────────────┤
    │ 42          │
    └─────────────┘