chore: define timedelta type and to_timedelta function (#1317)

* define timedelta type and to_timedelta function

* remove unnecessary file

* remove TypeAlias type for 3.9 compatibility

* fix mypy

* fix lint

* move timedelta out of the simple dtype list

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* fix type casts in tests

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: sycai

bigframes/core/compile/ibis_types.py

@@ -81,6 +81,7 @@
 BIGFRAMES_TO_IBIS: Dict[bigframes.dtypes.Dtype, ibis_dtypes.DataType] = {
     pandas: ibis for ibis, pandas in BIDIRECTIONAL_MAPPINGS
 }
+BIGFRAMES_TO_IBIS.update({bigframes.dtypes.TIMEDETLA_DTYPE: ibis_dtypes.int64})
 IBIS_TO_BIGFRAMES: Dict[ibis_dtypes.DataType, bigframes.dtypes.Dtype] = {
     ibis: pandas for ibis, pandas in BIDIRECTIONAL_MAPPINGS
 }

bigframes/core/compile/scalar_op_compiler.py

@@ -1140,6 +1140,13 @@ def to_timestamp_op_impl(x: ibis_types.Value, op: ops.ToTimestampOp):
     return x.cast(ibis_dtypes.Timestamp(timezone="UTC"))
 
 
+@scalar_op_compiler.register_unary_op(ops.ToTimedeltaOp, pass_op=True)
+def to_timedelta_op_impl(x: ibis_types.Value, op: ops.ToTimedeltaOp):
+    return (
+        typing.cast(ibis_types.NumericValue, x) * UNIT_TO_US_CONVERSION_FACTORS[op.unit]  # type: ignore
+    ).floor()
+
+
 @scalar_op_compiler.register_unary_op(ops.RemoteFunctionOp, pass_op=True)
 def remote_function_op_impl(x: ibis_types.Value, op: ops.RemoteFunctionOp):
     ibis_node = getattr(op.func, "ibis_node", None)

bigframes/dtypes.py

@@ -55,6 +55,7 @@
 TIME_DTYPE = pd.ArrowDtype(pa.time64("us"))
 DATETIME_DTYPE = pd.ArrowDtype(pa.timestamp("us"))
 TIMESTAMP_DTYPE = pd.ArrowDtype(pa.timestamp("us", tz="UTC"))
+TIMEDETLA_DTYPE = pd.ArrowDtype(pa.duration("us"))
 NUMERIC_DTYPE = pd.ArrowDtype(pa.decimal128(38, 9))
 BIGNUMERIC_DTYPE = pd.ArrowDtype(pa.decimal256(76, 38))
 # No arrow equivalent
@@ -632,6 +633,9 @@ def convert_to_schema_field(
             return google.cloud.bigquery.SchemaField(
                 name, "RECORD", fields=inner_fields
             )
+        if bigframes_dtype.pyarrow_dtype == pa.duration("us"):
+            # Timedeltas are represented as integers in microseconds.
+            return google.cloud.bigquery.SchemaField(name, "INTEGER")
     raise ValueError(
         f"No arrow conversion for {bigframes_dtype}. {constants.FEEDBACK_LINK}"
     )

bigframes/operations/__init__.py

@@ -170,6 +170,7 @@
 )
 from bigframes.operations.struct_ops import StructFieldOp, StructOp
 from bigframes.operations.time_ops import hour_op, minute_op, normalize_op, second_op
+from bigframes.operations.timedelta_ops import ToTimedeltaOp
 
 __all__ = [
     # Base ops
@@ -240,6 +241,8 @@
     "minute_op",
     "second_op",
     "normalize_op",
+    # Timedelta ops
+    "ToTimedeltaOp",
     # Datetime ops
     "date_op",
     "time_op",

bigframes/operations/timedelta_ops.py

@@ -0,0 +1,31 @@
+# Copyright 2025 Google LLC
+#
+# Licensed 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.
+
+
+import dataclasses
+import typing
+
+from bigframes import dtypes
+from bigframes.operations import base_ops
+
+
+@dataclasses.dataclass(frozen=True)
+class ToTimedeltaOp(base_ops.UnaryOp):
+    name: typing.ClassVar[str] = "to_timedelta"
+    unit: typing.Literal["us", "ms", "s", "m", "h", "d", "W"]
+
+    def output_type(self, *input_types):
+        if input_types[0] is not dtypes.INT_DTYPE:
+            raise TypeError("expected integer input")
+        return dtypes.TIMEDETLA_DTYPE

bigframes/pandas/__init__.py

@@ -35,6 +35,7 @@
 import bigframes.dataframe
 import bigframes.enums
 import bigframes.functions._utils as bff_utils
+from bigframes.pandas.core.api import to_timedelta
 from bigframes.pandas.io.api import (
     from_glob_path,
     read_csv,
@@ -313,6 +314,7 @@ def reset_session():
     "read_pickle",
     "remote_function",
     "to_datetime",
+    "to_timedelta",
     "from_glob_path",
     # pandas dtype attributes
     "NA",

bigframes/pandas/core/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2025 Google LLC
+#
+# Licensed 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.

bigframes/pandas/core/api.py

@@ -0,0 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# Licensed 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.
+
+from bigframes.pandas.core.tools.timedeltas import to_timedelta
+
+__all__ = ["to_timedelta"]

bigframes/pandas/core/tools/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2025 Google LLC
+#
+# Licensed 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.

bigframes/pandas/core/tools/timedeltas.py

@@ -0,0 +1,64 @@
+# Copyright 2025 Google LLC
+#
+# Licensed 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.
+
+import typing
+
+from bigframes_vendored.pandas.core.tools import (
+    timedeltas as vendored_pandas_timedeltas,
+)
+import pandas as pd
+
+from bigframes import operations as ops
+from bigframes import series
+
+
+def to_timedelta(
+    arg: typing.Union[series.Series, str, int, float],
+    unit: typing.Optional[vendored_pandas_timedeltas.UnitChoices] = None,
+) -> typing.Union[series.Series, pd.Timedelta]:
+    if not isinstance(arg, series.Series):
+        return pd.to_timedelta(arg, unit)
+
+    canonical_unit = "us" if unit is None else _canonicalize_unit(unit)
+    return arg._apply_unary_op(ops.ToTimedeltaOp(canonical_unit))
+
+
+to_timedelta.__doc__ = vendored_pandas_timedeltas.to_timedelta.__doc__
+
+
+def _canonicalize_unit(
+    unit: vendored_pandas_timedeltas.UnitChoices,
+) -> typing.Literal["us", "ms", "s", "m", "h", "d", "W"]:
+    if unit in {"w", "W"}:
+        return "W"
+
+    if unit in {"D", "d", "days", "day"}:
+        return "d"
+
+    if unit in {"hours", "hour", "hr", "h"}:
+        return "h"
+
+    if unit in {"m", "minute", "min", "minutes"}:
+        return "m"
+
+    if unit in {"s", "seconds", "sec", "second"}:
+        return "s"
+
+    if unit in {"ms", "milliseconds", "millisecond", "milli", "millis"}:
+        return "ms"
+
+    if unit in {"us", "microseconds", "microsecond", "µs", "micro", "micros"}:
+        return "us"
+
+    raise TypeError(f"Unrecognized unit: {unit}")