# Licensed to the Apache Software Foundation (ASF) under one

# or more contributor license agreements. See the NOTICE file

# distributed with this work for additional information

# regarding copyright ownership. The ASF licenses this file

# to you under the Apache License, Version 2.0 (the

# "License"); you may not use this file except in compliance

# with the License. You may obtain a copy of the License at

#

# http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing,

# software distributed under the License is distributed on an

# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

# KIND, either express or implied. See the License for the

# specific language governing permissions and limitations

# under the License.

"""User functions for operating on :py:class:`~datafusion.expr.Expr`."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

import pyarrow as pa

from datafusion._internal import functions as f

from datafusion.common import NullTreatment

from datafusion.expr import (

CaseBuilder,

Expr,

SortExpr,

SortKey,

WindowFrame,

expr_list_to_raw_expr_list,

sort_list_to_raw_sort_list,

sort_or_default,

)

try:

from warnings import deprecated # Python 3.13+

except ImportError:

from typing_extensions import deprecated # Python 3.12

if TYPE_CHECKING:

from datafusion.context import SessionContext

__all__ = [

"abs",

"acos",

"acosh",

"alias",

"approx_distinct",

"approx_median",

"approx_percentile_cont",

"approx_percentile_cont_with_weight",

"array",

"array_agg",

"array_any_value",

"array_append",

"array_cat",

"array_concat",

"array_contains",

"array_dims",

"array_distance",

"array_distinct",

"array_element",

"array_empty",

"array_except",

"array_extract",

"array_has",

"array_has_all",

"array_has_any",

"array_indexof",

"array_intersect",

"array_join",

"array_length",

"array_max",

"array_min",

"array_ndims",

"array_pop_back",

"array_pop_front",

"array_position",

"array_positions",

"array_prepend",

"array_push_back",

"array_push_front",

"array_remove",

"array_remove_all",

"array_remove_n",

"array_repeat",

"array_replace",

"array_replace_all",

"array_replace_n",

"array_resize",

"array_reverse",

"array_slice",

"array_sort",

"array_to_string",

"array_union",

"arrays_overlap",

"arrays_zip",

"arrow_cast",

"arrow_metadata",

"arrow_typeof",

"ascii",

"asin",

"asinh",

"atan",

"atan2",

"atanh",

"avg",

"bit_and",

"bit_length",

"bit_or",

"bit_xor",

"bool_and",

"bool_or",

"btrim",

"cardinality",

"case",

"cbrt",

"ceil",

"char_length",

"character_length",

"chr",

"coalesce",

"col",

"concat",

"concat_ws",

"contains",

"corr",

"cos",

"cosh",

"cot",

"count",

"count_star",

"covar",

"covar_pop",

"covar_samp",

"cume_dist",

"current_date",

"current_time",

"current_timestamp",

"date_bin",

"date_format",

"date_part",

"date_trunc",

"datepart",

"datetrunc",

"decode",

"degrees",

"dense_rank",

"digest",

"element_at",

"empty",

"encode",

"ends_with",

"exp",

"extract",

"factorial",

"find_in_set",

"first_value",

"flatten",

"floor",

"from_unixtime",

"gcd",

"gen_series",

"generate_series",

"get_field",

"greatest",

"grouping",

"ifnull",

"in_list",

"initcap",

"isnan",

"iszero",

"lag",

"last_value",

"lcm",

"lead",

"least",

"left",

"length",

"levenshtein",

"list_any_value",

"list_append",

"list_cat",

"list_concat",

"list_contains",

"list_dims",

"list_distance",

"list_distinct",

"list_element",

"list_empty",

"list_except",

"list_extract",

"list_has",

"list_has_all",

"list_has_any",

"list_indexof",

"list_intersect",

"list_join",

"list_length",

"list_max",

"list_min",

"list_ndims",

"list_overlap",

"list_pop_back",

"list_pop_front",

"list_position",

"list_positions",

"list_prepend",

"list_push_back",

"list_push_front",

"list_remove",

"list_remove_all",

"list_remove_n",

"list_repeat",

"list_replace",

"list_replace_all",

"list_replace_n",

"list_resize",

"list_reverse",

"list_slice",

"list_sort",

"list_to_string",

"list_union",

"list_zip",

"ln",

"log",

"log2",

"log10",

"lower",

"lpad",

"ltrim",

"make_array",

"make_date",

"make_list",

"make_map",

"make_time",

"map_entries",

"map_extract",

"map_keys",

"map_values",

"max",

"md5",

"mean",

"median",

"min",

"named_struct",

"nanvl",

"now",

"nth_value",

"ntile",

"nullif",

"nvl",

"nvl2",

"octet_length",

"order_by",

"overlay",

"percent_rank",

"percentile_cont",

"pi",

"pow",

"power",

"quantile_cont",

"radians",

"random",

"range",

"rank",

"regexp_count",

"regexp_instr",

"regexp_like",

"regexp_match",

"regexp_replace",

"regr_avgx",

"regr_avgy",

"regr_count",

"regr_intercept",

"regr_r2",

"regr_slope",

"regr_sxx",

"regr_sxy",

"regr_syy",

"repeat",

"replace",

"reverse",

"right",

"round",

"row",

"row_number",

"rpad",

"rtrim",

"sha224",

"sha256",

"sha384",

"sha512",

"signum",

"sin",

"sinh",

"split_part",

"sqrt",

"starts_with",

"stddev",

"stddev_pop",

"stddev_samp",

"string_agg",

"string_to_array",

"string_to_list",

"strpos",

"struct",

"substr",

"substr_index",

"substring",

"sum",

"tan",

"tanh",

"to_char",

"to_date",

"to_hex",

"to_local_time",

"to_time",

"to_timestamp",

"to_timestamp_micros",

"to_timestamp_millis",

"to_timestamp_nanos",

"to_timestamp_seconds",

"to_unixtime",

"today",

"translate",

"trim",

"trunc",

"union_extract",

"union_tag",

"upper",

"uuid",

"var",

"var_pop",

"var_population",

"var_samp",

"var_sample",

"version",

"when",

# Window Functions

"window",

]

def isnan(expr: Expr) -> Expr:

"""Returns true if a given number is +NaN or -NaN otherwise returns false.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1.0, np.nan]})

>>> result = df.select(dfn.functions.isnan(dfn.col("a")).alias("isnan"))

>>> result.collect_column("isnan")[1].as_py()

True

"""

return Expr(f.isnan(expr.expr))

def nullif(expr1: Expr, expr2: Expr) -> Expr:

"""Returns NULL if expr1 equals expr2; otherwise it returns expr1.

This can be used to perform the inverse operation of the COALESCE expression.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1, 2], "b": [1, 3]})

>>> result = df.select(

... dfn.functions.nullif(dfn.col("a"), dfn.col("b")).alias("nullif"))

>>> result.collect_column("nullif").to_pylist()

[None, 2]

"""

return Expr(f.nullif(expr1.expr, expr2.expr))

def encode(expr: Expr, encoding: Expr) -> Expr:

"""Encode the ``input``, using the ``encoding``. encoding can be base64 or hex.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["hello"]})

>>> result = df.select(

... dfn.functions.encode(dfn.col("a"), dfn.lit("base64")).alias("enc"))

>>> result.collect_column("enc")[0].as_py()

'aGVsbG8'

"""

return Expr(f.encode(expr.expr, encoding.expr))

def decode(expr: Expr, encoding: Expr) -> Expr:

"""Decode the ``input``, using the ``encoding``. encoding can be base64 or hex.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["aGVsbG8="]})

>>> result = df.select(

... dfn.functions.decode(dfn.col("a"), dfn.lit("base64")).alias("dec"))

>>> result.collect_column("dec")[0].as_py()

b'hello'

"""

return Expr(f.decode(expr.expr, encoding.expr))

def array_to_string(expr: Expr, delimiter: Expr) -> Expr:

"""Converts each element to its text representation.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [[1, 2, 3]]})

>>> result = df.select(

... dfn.functions.array_to_string(dfn.col("a"), dfn.lit(",")).alias("s"))

>>> result.collect_column("s")[0].as_py()

'1,2,3'

"""

return Expr(f.array_to_string(expr.expr, delimiter.expr.cast(pa.string())))

def array_join(expr: Expr, delimiter: Expr) -> Expr:

"""Converts each element to its text representation.

See Also:

This is an alias for :py:func:`array_to_string`.

"""

return array_to_string(expr, delimiter)

def list_to_string(expr: Expr, delimiter: Expr) -> Expr:

"""Converts each element to its text representation.

See Also:

This is an alias for :py:func:`array_to_string`.

"""

return array_to_string(expr, delimiter)

def list_join(expr: Expr, delimiter: Expr) -> Expr:

"""Converts each element to its text representation.

See Also:

This is an alias for :py:func:`array_to_string`.

"""

return array_to_string(expr, delimiter)

def in_list(arg: Expr, values: list[Expr], negated: bool = False) -> Expr:

"""Returns whether the argument is contained within the list ``values``.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1, 2, 3]})

>>> result = df.select(

... dfn.functions.in_list(

... dfn.col("a"), [dfn.lit(1), dfn.lit(3)]

... ).alias("in")

... )

>>> result.collect_column("in").to_pylist()

[True, False, True]

>>> result = df.select(

... dfn.functions.in_list(

... dfn.col("a"), [dfn.lit(1), dfn.lit(3)],

... negated=True,

... ).alias("not_in")

... )

>>> result.collect_column("not_in").to_pylist()

[False, True, False]

"""

values = [v.expr for v in values]

return Expr(f.in_list(arg.expr, values, negated))

def digest(value: Expr, method: Expr) -> Expr:

"""Computes the binary hash of an expression using the specified algorithm.

Standard algorithms are md5, sha224, sha256, sha384, sha512, blake2s,

blake2b, and blake3.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["hello"]})

>>> result = df.select(

... dfn.functions.digest(dfn.col("a"), dfn.lit("md5")).alias("d"))

>>> len(result.collect_column("d")[0].as_py()) > 0

True

"""

return Expr(f.digest(value.expr, method.expr))

def contains(string: Expr, search_str: Expr) -> Expr:

"""Returns true if ``search_str`` is found within ``string`` (case-sensitive).

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["the quick brown fox"]})

>>> result = df.select(

... dfn.functions.contains(dfn.col("a"), dfn.lit("brown")).alias("c"))

>>> result.collect_column("c")[0].as_py()

True

"""

return Expr(f.contains(string.expr, search_str.expr))

def concat(*args: Expr) -> Expr:

"""Concatenates the text representations of all the arguments.

NULL arguments are ignored.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["hello"], "b": [" world"]})

>>> result = df.select(

... dfn.functions.concat(dfn.col("a"), dfn.col("b")).alias("c")

... )

>>> result.collect_column("c")[0].as_py()

'hello world'

"""

args = [arg.expr for arg in args]

return Expr(f.concat(args))

def concat_ws(separator: str, *args: Expr) -> Expr:

"""Concatenates the list ``args`` with the separator.

``NULL`` arguments are ignored. ``separator`` should not be ``NULL``.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["hello"], "b": ["world"]})

>>> result = df.select(

... dfn.functions.concat_ws("-", dfn.col("a"), dfn.col("b")).alias("c"))

>>> result.collect_column("c")[0].as_py()

'hello-world'

"""

args = [arg.expr for arg in args]

return Expr(f.concat_ws(separator, args))

def order_by(expr: Expr, ascending: bool = True, nulls_first: bool = True) -> SortExpr:

"""Creates a new sort expression.

Examples:

>>> sort_expr = dfn.functions.order_by(

... dfn.col("a"), ascending=False)

>>> sort_expr.ascending()

False

>>> sort_expr = dfn.functions.order_by(

... dfn.col("a"), ascending=True, nulls_first=False)

>>> sort_expr.nulls_first()

False

"""

return SortExpr(expr, ascending=ascending, nulls_first=nulls_first)

def alias(expr: Expr, name: str, metadata: dict[str, str] | None = None) -> Expr:

"""Creates an alias expression with an optional metadata dictionary.

Args:

expr: The expression to alias

name: The alias name

metadata: Optional metadata to attach to the column

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1, 2]})

>>> result = df.select(

... dfn.functions.alias(

... dfn.col("a"), "b"

... )

... )

>>> result.collect_column("b")[0].as_py()

1

>>> result = df.select(

... dfn.functions.alias(

... dfn.col("a"), "b", metadata={"info": "test"}

... )

... )

>>> result.schema()

b: int64

-- field metadata --

info: 'test'

"""

return Expr(f.alias(expr.expr, name, metadata))

def col(name: str) -> Expr:

"""Creates a column reference expression.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1, 2, 3]})

>>> df.select(dfn.functions.col("a")).collect_column("a")[0].as_py()

1

"""

return Expr(f.col(name))

def count_star(filter: Expr | None = None) -> Expr:

"""Create a COUNT(1) aggregate expression.

This aggregate function will count all of the rows in the partition.

If using the builder functions described in ref:`_aggregation` this function ignores

the options ``order_by``, ``distinct``, and ``null_treatment``.

Args:

filter: If provided, only count rows for which the filter is True

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1, 2, 3]})

>>> result = df.aggregate(

... [], [dfn.functions.count_star(

... ).alias("cnt")])

>>> result.collect_column("cnt")[0].as_py()

3

>>> result = df.aggregate(

... [], [dfn.functions.count_star(

... filter=dfn.col("a") > dfn.lit(1)

... ).alias("cnt")])

>>> result.collect_column("cnt")[0].as_py()

2

"""

return count(Expr.literal(1), filter=filter)

def case(expr: Expr) -> CaseBuilder:

"""Create a case expression.

Create a :py:class:`~datafusion.expr.CaseBuilder` to match cases for the

expression ``expr``. See :py:class:`~datafusion.expr.CaseBuilder` for

detailed usage.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1, 2, 3]})

>>> result = df.select(

... dfn.functions.case(dfn.col("a")).when(dfn.lit(1),

... dfn.lit("one")).otherwise(dfn.lit("other")).alias("c"))

>>> result.collect_column("c")[0].as_py()

'one'

"""

return CaseBuilder(f.case(expr.expr))

def when(when: Expr, then: Expr) -> CaseBuilder:

"""Create a case expression that has no base expression.

Create a :py:class:`~datafusion.expr.CaseBuilder` to match cases for the

expression ``expr``. See :py:class:`~datafusion.expr.CaseBuilder` for

detailed usage.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1, 2, 3]})

>>> result = df.select(

... dfn.functions.when(dfn.col("a") > dfn.lit(2),

... dfn.lit("big")).otherwise(dfn.lit("small")).alias("c"))

>>> result.collect_column("c")[2].as_py()

'big'

"""

return CaseBuilder(f.when(when.expr, then.expr))

@deprecated("Prefer to call Expr.over() instead")

def window(

name: str,

args: list[Expr],

partition_by: list[Expr] | Expr | None = None,

order_by: list[SortKey] | SortKey | None = None,

window_frame: WindowFrame | None = None,

filter: Expr | None = None,

distinct: bool = False,

ctx: SessionContext | None = None,

) -> Expr:

"""Creates a new Window function expression.

This interface will soon be deprecated. Instead of using this interface,

users should call the window functions directly. For example, to perform a

lag use::

df.select(functions.lag(col("a")).partition_by(col("b")).build())

The ``order_by`` parameter accepts column names or expressions, e.g.::

window("lag", [col("a")], order_by="ts")

"""

args = [a.expr for a in args]

partition_by_raw = expr_list_to_raw_expr_list(partition_by)

order_by_raw = sort_list_to_raw_sort_list(order_by)

window_frame = window_frame.window_frame if window_frame is not None else None

ctx = ctx.ctx if ctx is not None else None

filter_raw = filter.expr if filter is not None else None

return Expr(

f.window(

name,

args,

partition_by=partition_by_raw,

order_by=order_by_raw,

window_frame=window_frame,

ctx=ctx,

filter=filter_raw,

distinct=distinct,

)

)

# scalar functions

def abs(arg: Expr) -> Expr:

"""Return the absolute value of a given number.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [-1, 0, 1]})

>>> result = df.select(dfn.functions.abs(dfn.col("a")).alias("abs"))

>>> result.collect_column("abs")[0].as_py()

1

"""

return Expr(f.abs(arg.expr))

def acos(arg: Expr) -> Expr:

"""Returns the arc cosine or inverse cosine of a number.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1.0]})

>>> result = df.select(dfn.functions.acos(dfn.col("a")).alias("acos"))

>>> result.collect_column("acos")[0].as_py()

0.0

"""

return Expr(f.acos(arg.expr))

def acosh(arg: Expr) -> Expr:

"""Returns inverse hyperbolic cosine.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1.0]})

>>> result = df.select(dfn.functions.acosh(dfn.col("a")).alias("acosh"))

>>> result.collect_column("acosh")[0].as_py()

0.0

"""

return Expr(f.acosh(arg.expr))

def ascii(arg: Expr) -> Expr:

"""Returns the numeric code of the first character of the argument.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["a","b","c"]})

>>> ascii_df = df.select(dfn.functions.ascii(dfn.col("a")).alias("ascii"))

>>> ascii_df.collect_column("ascii")[0].as_py()

97

"""

return Expr(f.ascii(arg.expr))

def asin(arg: Expr) -> Expr:

"""Returns the arc sine or inverse sine of a number.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [0.0]})

>>> result = df.select(dfn.functions.asin(dfn.col("a")).alias("asin"))

>>> result.collect_column("asin")[0].as_py()

0.0

"""

return Expr(f.asin(arg.expr))

def asinh(arg: Expr) -> Expr:

"""Returns inverse hyperbolic sine.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [0.0]})

>>> result = df.select(dfn.functions.asinh(dfn.col("a")).alias("asinh"))

>>> result.collect_column("asinh")[0].as_py()

0.0

"""

return Expr(f.asinh(arg.expr))

def atan(arg: Expr) -> Expr:

"""Returns inverse tangent of a number.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [0.0]})

>>> result = df.select(dfn.functions.atan(dfn.col("a")).alias("atan"))

>>> result.collect_column("atan")[0].as_py()

0.0

"""

return Expr(f.atan(arg.expr))

def atanh(arg: Expr) -> Expr:

"""Returns inverse hyperbolic tangent.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [0.0]})

>>> result = df.select(dfn.functions.atanh(dfn.col("a")).alias("atanh"))

>>> result.collect_column("atanh")[0].as_py()

0.0

"""

return Expr(f.atanh(arg.expr))

def atan2(y: Expr, x: Expr) -> Expr:

"""Returns inverse tangent of a division given in the argument.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"y": [0.0], "x": [1.0]})

>>> result = df.select(

... dfn.functions.atan2(dfn.col("y"), dfn.col("x")).alias("atan2"))

>>> result.collect_column("atan2")[0].as_py()

0.0

"""

return Expr(f.atan2(y.expr, x.expr))

def bit_length(arg: Expr) -> Expr:

"""Returns the number of bits in the string argument.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["a","b","c"]})

>>> bit_df = df.select(dfn.functions.bit_length(dfn.col("a")).alias("bit_len"))

>>> bit_df.collect_column("bit_len")[0].as_py()

8

"""

return Expr(f.bit_length(arg.expr))

def btrim(arg: Expr) -> Expr:

"""Removes all characters, spaces by default, from both sides of a string.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [" a "]})

>>> trim_df = df.select(dfn.functions.btrim(dfn.col("a")).alias("trimmed"))

>>> trim_df.collect_column("trimmed")[0].as_py()

'a'

"""

return Expr(f.btrim(arg.expr))

def cbrt(arg: Expr) -> Expr:

"""Returns the cube root of a number.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [27]})

>>> cbrt_df = df.select(dfn.functions.cbrt(dfn.col("a")).alias("cbrt"))

>>> cbrt_df.collect_column("cbrt")[0].as_py()

3.0

"""

return Expr(f.cbrt(arg.expr))

def ceil(arg: Expr) -> Expr:

"""Returns the nearest integer greater than or equal to argument.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [1.9]})

>>> ceil_df = df.select(dfn.functions.ceil(dfn.col("a")).alias("ceil"))

>>> ceil_df.collect_column("ceil")[0].as_py()

2.0

"""

return Expr(f.ceil(arg.expr))

def character_length(arg: Expr) -> Expr:

"""Returns the number of characters in the argument.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["abc","b","c"]})

>>> char_len_df = df.select(

... dfn.functions.character_length(dfn.col("a")).alias("char_len"))

>>> char_len_df.collect_column("char_len")[0].as_py()

3

"""

return Expr(f.character_length(arg.expr))

def length(string: Expr) -> Expr:

"""The number of characters in the ``string``.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["hello"]})

>>> result = df.select(dfn.functions.length(dfn.col("a")).alias("len"))

>>> result.collect_column("len")[0].as_py()

5

"""

return Expr(f.length(string.expr))

def char_length(string: Expr) -> Expr:

"""The number of characters in the ``string``.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": ["hello"]})

>>> result = df.select(dfn.functions.char_length(dfn.col("a")).alias("len"))

>>> result.collect_column("len")[0].as_py()

5

"""

return Expr(f.char_length(string.expr))

def chr(arg: Expr) -> Expr:

"""Converts the Unicode code point to a UTF8 character.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [65]})

>>> result = df.select(dfn.functions.chr(dfn.col("a")).alias("chr"))

>>> result.collect_column("chr")[0].as_py()

'A'

"""

return Expr(f.chr(arg.expr))

def coalesce(*args: Expr) -> Expr:

"""Returns the value of the first expr in ``args`` which is not NULL.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [None, 1], "b": [2, 3]})

>>> result = df.select(

... dfn.functions.coalesce(dfn.col("a"), dfn.col("b")).alias("c"))

>>> result.collect_column("c")[0].as_py()

2

"""

args = [arg.expr for arg in args]

return Expr(f.coalesce(*args))

def cos(arg: Expr) -> Expr:

"""Returns the cosine of the argument.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [0,-1,1]})

>>> cos_df = df.select(dfn.functions.cos(dfn.col("a")).alias("cos"))

>>> cos_df.collect_column("cos")[0].as_py()

1.0

"""

return Expr(f.cos(arg.expr))

def cosh(arg: Expr) -> Expr:

"""Returns the hyperbolic cosine of the argument.

Examples:

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [0,-1,1]})

>>> cosh_df = df.select(dfn.functions.cosh(dfn.col("a")).alias("cosh"))

>>> cosh_df.collect_column("cosh")[0].as_py()

1.0

"""

return Expr(f.cosh(arg.expr))

def cot(arg: Expr) -> Expr:

"""Returns the cotangent of the argument.

Examples:

>>> from math import pi

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [pi / 4]})

>>> result = df.select(

... dfn.functions.cot(dfn.col("a")).alias("cot")

... )

>>> result.collect_column("cot")[0].as_py()

1.0...

"""

return Expr(f.cot(arg.expr))

def degrees(arg: Expr) -> Expr:

"""Converts the argument from radians to degrees.

Examples:

>>> from math import pi

>>> ctx = dfn.SessionContext()

>>> df = ctx.from_pydict({"a": [0,pi,2*pi]})

>>> deg_df = df.select(dfn.functions.degrees(dfn.col("a")).alias("deg"))

>>> deg_df.collect_column("deg")[2].as_py()

360.0