polars.Series.str.to_datetime#

Series.str.to_datetime(
format: str | None = None,
*,
time_unit: TimeUnit | None = None,
time_zone: str | None = None,
strict: bool = True,
exact: bool = True,
cache: bool = True,
ambiguous: Ambiguous | Series = 'raise',
) → Series[source]#

Convert a String column into a Datetime column.

Parameters:
format

Format to use for conversion. Refer to the chrono crate documentation for the full specification. Example: "%Y-%m-%d %H:%M:%S". If set to None (default), the format is inferred from the data.

time_unit{None, ‘us’, ‘ns’, ‘ms’}

Unit of time for the resulting Datetime column. If set to None (default), the time unit is inferred from the format string if given, eg: "%F %T%.3f" => Datetime("ms"). If no fractional second component is found, the default is "us".

time_zone

Time zone for the resulting Datetime column. Rules are:

  • If inputs are tz-naive and time_zone is None, the result time zone is None.

  • If inputs are offset-aware and time_zone is None, inputs are converted to 'UTC' and the result time zone is 'UTC'.

  • If inputs are offset-aware and time_zone is given, inputs are converted to time_zone and the result time zone is time_zone.

  • If inputs are tz-naive and time_zone is given, input time zones are replaced with (not converted to!) time_zone, and the result time zone is time_zone.

strict

Raise an error if any conversion fails.

exact

Require an exact format match. If False, allow the format to match anywhere in the target string.

Note

Using exact=False introduces a performance penalty - cleaning your data beforehand will almost certainly be more performant.

cache

Use a cache of unique, converted datetimes to apply the conversion.

ambiguous

Determine how to handle daylight savings time (DST) ambiguous datetimes (e.g., when the clock falls back and the same local time occurs twice).

  • ‘earliest’: use the earliest datetime

  • ‘latest’: use the latest datetime

  • ‘raise’: raise an error

  • ‘null’: set to null

Examples

>>> s = pl.Series(["2020-01-01 01:00Z", "2020-01-01 02:00Z"])
>>> s.str.to_datetime("%Y-%m-%d %H:%M%#z")
shape: (2,)
Series: '' [datetime[μs, UTC]]
[
        2020-01-01 01:00:00 UTC
        2020-01-01 02:00:00 UTC
]