bigframes.pandas.to_datetime(arg: vendored_pandas_datetimes.local_iterables | bigframes.series.Series | bigframes.dataframe.DataFrame, *, utc: bool = False, format: str | None = None, unit: str | None = None) → bigframes.series.Series[source]#
bigframes.pandas.to_datetime(arg: int | float | str | datetime.datetime | datetime.date, *, utc: bool = False, format: str | None = None, unit: str | None = None) → pandas.Timestamp | datetime.datetime

This function converts a scalar, array-like or Series to a datetime object.

Note

BigQuery only supports precision up to microseconds (us). Therefore, when working with timestamps that have a finer granularity than microseconds, be aware that the additional precision will not be represented in BigQuery.

Examples:

>>> import bigframes.pandas as bpd

Converting a Scalar to datetime:

>>> scalar = 123456.789
>>> bpd.to_datetime(scalar, unit = 's')
Timestamp('1970-01-02 10:17:36.789000')

Converting a List of Strings without Timezone Information:

>>> list_str = ["01-31-2021 14:30", "02-28-2021 15:45"]
>>> bpd.to_datetime(list_str, format="%m-%d-%Y %H:%M", utc=True)
0    2021-01-31 14:30:00+00:00
1    2021-02-28 15:45:00+00:00
dtype: timestamp[us, tz=UTC][pyarrow]

Converting a Series of Strings with Timezone Information:

>>> series_str = bpd.Series(["01-31-2021 14:30+08:00", "02-28-2021 15:45+00:00"])
>>> bpd.to_datetime(series_str, format="%m-%d-%Y %H:%M%Z", utc=True)
0    2021-01-31 06:30:00+00:00
1    2021-02-28 15:45:00+00:00
dtype: timestamp[us, tz=UTC][pyarrow]
Parameters:

  • arg (int, float, str, datetime, date, list, tuple, 1-d array, Series) – The object to convert to a datetime.

  • utc (bool, default False) – Control timezone-related parsing, localization and conversion. If True, the function always returns a timezone-aware UTC-localized timestamp or series. If False (default), inputs will not be coerced to UTC.

  • format (str, default None) – The strftime to parse time, e.g. “%d/%m/%Y”.

  • unit (str, default 'ns') – The unit of the arg (D,s,ms,us,ns) denote the unit, which is an integer or float number.

Returns:

Return type depends on input.

Return type:

Union[pandas.Timestamp, datetime.datetime or bigframes.pandas.Series]