Scalar UDFs

Scalar user-defined function APIs

scalar

scalar()

Scalar user-defined functions.

The scalar class itself is not a public API, its methods are.

Methods

Name Description
builtin Construct a scalar user-defined function that is built-in to the backend.
pandas Construct a vectorized scalar user-defined function that accepts pandas Series’ as inputs.
pyarrow Construct a vectorized scalar user-defined function that accepts PyArrow Arrays as input.
python Construct a non-vectorized scalar user-defined function that accepts Python scalar values as inputs.

builtin

builtin(fn=None, *, name=None, schema=None, signature=None, **kwargs)

Construct a scalar user-defined function that is built-in to the backend.

Parameters

Name Type Description Default
fn The function to wrap. None
name The name of the UDF in the backend if different from the function name. None
schema The schema in which the builtin function resides. None
signature An optional signature to use for the UDF. If present, should be a tuple containing a tuple of argument types and a return type. For example, a function taking an int and a float and returning a string would be ((int, float), str). If not present, the argument types will be derived from the wrapped function. None
kwargs Additional backend-specific configuration arguments for the UDF. {}

Examples

>>> import ibis
>>> @ibis.udf.scalar.builtin
... def hamming(a: str, b: str) -> int:
...     '''Compute the Hamming distance between two strings.'''
>>> expr = hamming("duck", "luck")
>>> con = ibis.connect("duckdb://")
>>> con.execute(expr)
1

pandas

pandas(fn=None, *, name=None, schema=None, signature=None, **kwargs)

Construct a vectorized scalar user-defined function that accepts pandas Series’ as inputs.

Parameters

Name Type Description Default
fn The function to wrap. None
name The name of the UDF in the backend if different from the function name. None
schema The schema in which to create the UDF. None
signature An optional signature to use for the UDF. If present, should be a tuple containing a tuple of argument types and a return type. For example, a function taking an int and a float and returning a string would be ((int, float), str). If not present, the argument types will be derived from the wrapped function. None
kwargs Additional backend-specific configuration arguments for the UDF. {}

Examples

>>> import ibis
>>> @ibis.udf.scalar.pandas
... def add_one(x: int) -> int:
...     return x + 1
>>> expr = add_one(2)
>>> con = ibis.connect(os.environ["SNOWFLAKE_URL"])  # doctest: +SKIP
>>> con.execute(expr)  # doctest: +SKIP
3

See Also

pyarrow

pyarrow(fn=None, *, name=None, schema=None, signature=None, **kwargs)

Construct a vectorized scalar user-defined function that accepts PyArrow Arrays as input.

Parameters

Name Type Description Default
fn The function to wrap. None
name The name of the UDF in the backend if different from the function name. None
schema The schema in which to create the UDF. None
signature An optional signature to use for the UDF. If present, should be a tuple containing a tuple of argument types and a return type. For example, a function taking an int and a float and returning a string would be ((int, float), str). If not present, the argument types will be derived from the wrapped function. None
kwargs Additional backend-specific configuration arguments for the UDF. {}

Examples

>>> import ibis
>>> import pyarrow.compute as pc
>>> @ibis.udf.scalar.pyarrow
... def add_one(x: int) -> int:
...     return pc.add(x, 1)
>>> expr = add_one(2)
>>> con = ibis.connect("duckdb://")
>>> con.execute(expr)
3

See Also

python

python(fn=None, *, name=None, schema=None, signature=None, **kwargs)

Construct a non-vectorized scalar user-defined function that accepts Python scalar values as inputs.

python UDFs are not vectorized: they are executed row by row with one Python function call per row

This calling pattern tends to be much slower than pandas or pyarrow-based vectorized UDFs.

Parameters

Name Type Description Default
fn The function to wrap. None
name The name of the UDF in the backend if different from the function name. None
schema The schema in which to create the UDF. None
signature An optional signature to use for the UDF. If present, should be a tuple containing a tuple of argument types and a return type. For example, a function taking an int and a float and returning a string would be ((int, float), str). If not present, the argument types will be derived from the wrapped function. None
kwargs Additional backend-specific configuration arguments for the UDF. {}

Examples

>>> import ibis
>>> @ibis.udf.scalar.python
... def add_one(x: int) -> int:
...     return x + 1
>>> expr = add_one(2)
>>> con = ibis.connect("duckdb://")
>>> con.execute(expr)
3

See Also

Back to top