Python ユーザー定義関数（UDF）

chDB では、Python 関数を SQL から呼び出せる UDF として登録できます。これらはネイティブにインプロセスで実行されるため、サブプロセスの起動やシリアライゼーションのオーバーヘッドは発生しません。関数は型安全で、Python アノテーションに基づく自動型推論をサポートし、NULL と例外の処理を設定できます。

クイックスタート

from chdb import query, func
from chdb.sqltypes import INT64

@func([INT64, INT64], INT64)
def add(a, b):
    return a + b

result = query("SELECT add(2, 3)")
print(result)  # 5

登録方法

`@func` デコレータ

UDF を登録する最も簡単な方法です。関数の __name__ が SQL 関数名として使用されます。

from chdb import func
from chdb.sqltypes import INT64, STRING

# Explicit types
@func([INT64, INT64], INT64)
def add(a, b):
    return a + b

# Types inferred from annotations
@func()
def multiply(a: int, b: int) -> int:
    return a * b

# Explicit return_type, arg_types inferred from annotations
@func(return_type=STRING)
def greet(name: str):
    return f"Hello, {name}!"

デコレートされた関数は、通常の Python 関数と同様に引き続き呼び出せます。

add(2, 3)       # 5 (Python call)
query("SELECT add(2, 3)")  # 5 (SQL call)

`create_function`

任意の呼び出し可能なオブジェクト (lambda、関数、method) を明示的な名前で登録します。

from chdb import create_function, query
from chdb.sqltypes import INT64, STRING

create_function("strlen", len, arg_types=[STRING], return_type=INT64)
query("SELECT strlen('hello')")  # 5

create_function("double", lambda x: x * 2, arg_types=[INT64], return_type=INT64)
query("SELECT double(21)")  # 42

`drop_function`

登録済みの UDF を削除します。登録されていない名前を削除しようとしても何も起こらないため、無条件で安全に呼び出せます。

from chdb import drop_function

drop_function("strlen")
# query("SELECT strlen('hello')")  # Error: function not found

型システム

利用可能な型

すべての型は chdb.sqltypes からインポートできます。

from chdb.sqltypes import (
    # Boolean
    BOOL,
    # Signed integers
    INT8, INT16, INT32, INT64, INT128, INT256,
    # Unsigned integers
    UINT8, UINT16, UINT32, UINT64, UINT128, UINT256,
    # Floating point
    FLOAT32, FLOAT64,
    # String
    STRING,
    # Date and time
    DATE, DATE32, DATETIME, DATETIME64,
)

型の指定

型は次の 4 つの方法で指定できます。

方法	例	説明
`ChdbType` 定数	`INT64`, `STRING`	`chdb.sqltypes` からインポート
ClickHouse 型文字列	`"Int64"`, `"String"`	標準の ClickHouse 型名
パラメーター付き文字列	`"DateTime('UTC')"`, `"DateTime64(6)"`	パラメーターを持つ型に使用
Python 型	`int`, `str`, `float`	`arg_types`/`return_type` に直接渡すか、関数シグネチャの型アノテーションとして使用

from chdb import create_function, func
from chdb.sqltypes import INT64

# All equivalent:
create_function("f1", lambda x: x * 2, arg_types=[INT64], return_type=INT64)
create_function("f2", lambda x: x * 2, arg_types=["Int64"], return_type="Int64")
create_function("f3", lambda x: x * 2, arg_types=[int], return_type=int)

@func()
def f4(x: int) -> int:
    return x * 2

自動型推論

arg_types または return_type を省略すると、chDB は Python の型アノテーションから型を推論します。

Python 型	ClickHouse 型
`bool`	`Bool`
`int`	`Int64`
`float`	`Float64`
`str`	`String`
`bytes`	`String`
`bytearray`	`String`
`datetime.date`	`Date`
`datetime.datetime`	`DateTime64(6)`

@func()
def process(name: str, age: int) -> str:
    return f"{name} is {age} years old"

# Equivalent to:
# @func([STRING, INT64], STRING)

戻り値の型は常に必要です。return_type を省略し、関数に戻り値のアノテーションもない場合、登録に失敗します。一方、引数の型は任意です。明示的な型指定もアノテーションもないパラメータは、サポートされている任意の入力型を動的に受け入れます。

NULL の処理

on_null パラメータは、入力引数のいずれかが NULL の場合の動作を制御します。

値	動作
`"skip"` (デフォルト)	関数を呼び出さず、直ちに NULL を返します
`"pass"`	NULL を Python の `None` に変換し、通常どおり関数を呼び出します

enum も使用できます: chdb.NullHandling.SKIP / chdb.NullHandling.PASS。

例: default (スキップ)

@func(return_type="Int64")
def increment(x: int) -> int:
    return x + 1

query("SELECT increment(NULL)")  # NULL
query("SELECT increment(5)")     # 6

例: NULL を `None` として渡す

@func(return_type="Int64", on_null="pass")
def null_to_zero(x):
    return 0 if x is None else x + 1

query("SELECT null_to_zero(NULL)")  # 0
query("SELECT null_to_zero(5)")     # 6

例: 複数の引数

@func(arg_types=["Int64", "Int64"], return_type="Int64", on_null="pass")
def add_or_zero(a, b):
    return (a or 0) + (b or 0)

query("SELECT add_or_zero(NULL, 5)")    # 5
query("SELECT add_or_zero(NULL, NULL)") # 0
query("SELECT add_or_zero(3, 7)")       # 10

例外処理

on_error パラメータは、Python 関数で例外が発生した場合の動作を制御します。

値	動作
`"propagate"` (デフォルト)	例外を SQL エラーとして送出
`"ignore"`	例外を捕捉し、その行に対して NULL を返す

enum も使用できます: chdb.ExceptionHandling.PROPAGATE / chdb.ExceptionHandling.IGNORE。

例: default (伝播)

@func(arg_types=["Int64", "Int64"], return_type="Int64")
def divide(a, b):
    return a // b

query("SELECT divide(10, 2)")  # 5
query("SELECT divide(1, 0)")   # Error: ZeroDivisionError

例: エラーを無視する

@func(arg_types=["Int64", "Int64"], return_type="Int64", on_error="ignore")
def safe_divide(a, b):
    return a // b

query("SELECT safe_divide(10, 2)")  # 5
query("SELECT safe_divide(1, 0)")   # NULL

NULL と例外処理の組み合わせ

on_null オプションと on_error オプションは組み合わせて使用できます。

on_null	on_error	NULL 入力	例外
`"skip"`	`"propagate"`	NULL を返す	エラーを発生させる
`"skip"`	`"ignore"`	NULL を返す	NULL を返す
`"pass"`	`"propagate"`	`None` を指定して呼び出す	エラーを発生させる
`"pass"`	`"ignore"`	`None` を指定して呼び出す	NULL を返す

@func(
    arg_types=["Int64", "Int64"],
    return_type="Int64",
    on_null="pass",
    on_error="ignore",
)
def robust_divide(a, b):
    if a is None or b is None:
        return -1
    return a // b

query("SELECT robust_divide(10, 2)")     # 5
query("SELECT robust_divide(NULL, 2)")   # -1
query("SELECT robust_divide(1, 0)")      # NULL (exception caught)

DateTime とタイムゾーンのサポート

UDF は、タイムゾーンを認識する日付と時刻の型を完全にサポートしています。

Date 型

from datetime import date, timedelta

@func()
def next_day(d: date) -> date:
    return d + timedelta(days=1)

@func()
def get_year(d: date) -> int:
    return d.year

query("SELECT next_day(toDate('2024-06-15'))")  # 2024-06-16
query("SELECT get_year(toDate('2024-06-15'))")  # 2024

タイムゾーン付きDateTime

from datetime import timedelta

@func(arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")
def add_one_hour(dt):
    return dt + timedelta(hours=1)

query("SELECT add_one_hour(toDateTime('2024-01-01 12:00:00', 'UTC'))")  # 2024-01-01 13:00:00

DateTime64 (高精度)

DATETIME64 のデフォルトのスケールは6 (マイクロ秒) です。

from datetime import timedelta

@func(arg_types=["DateTime64(6, 'UTC')"], return_type="DateTime64(6, 'UTC')")
def add_microsecond(dt):
    return dt + timedelta(microseconds=1)

query("SELECT add_microsecond(toDateTime64('2024-01-01 12:00:00.000000', 6, 'UTC'))")  # 2024-01-01 12:00:00.000001

sessions で UDF を使用する

UDF はグローバルに登録され、同じプロセス内のすべての sessions で利用できます。

from chdb import session as chs, func
from chdb.sqltypes import INT64

@func([INT64], INT64)
def double(x):
    return x * 2

sess = chs.Session()
sess.query("CREATE TABLE t (x Int64) ENGINE = Memory")
sess.query("INSERT INTO t VALUES (1), (2), (3)")
result = sess.query("SELECT double(x) FROM t ORDER BY x", "CSV")
print(result)
# 2
# 4
# 6