narwhals.Series.dt

convert_time_zone

convert_time_zone(time_zone: str) -> SeriesT

Convert time zone.

If converting from a time-zone-naive column, then conversion happens as if converting from UTC.

Parameters:

Name	Type	Description	Default
time_zone	str	Target time zone.	required

Returns:

Type	Description
SeriesT	A new Series with the specified time zone.

Examples:

>>> from datetime import datetime, timezone
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [
...         datetime(2024, 1, 1, tzinfo=timezone.utc),
...         datetime(2024, 1, 2, tzinfo=timezone.utc),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.convert_time_zone("Asia/Kathmandu").to_native()
0   2024-01-01 05:45:00+05:45
1   2024-01-02 05:45:00+05:45
dtype: datetime64[ns, Asia/Kathmandu]

date

date() -> SeriesT

Get the date in a datetime series.

Returns:

Type	Description
SeriesT	A new Series with the date portion of the datetime values.

Raises:

Type	Description
NotImplementedError	If pandas default backend is being used.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [datetime(2012, 1, 7, 10, 20), datetime(2023, 3, 10, 11, 32)]
... ).convert_dtypes(dtype_backend="pyarrow")
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.date().to_native()
0    2012-01-07
1    2023-03-10
dtype: date32[day][pyarrow]

day

day() -> SeriesT

Extracts the day in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the day component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2022, 1, 1), datetime(2022, 1, 5)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.day().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    1,
    5
  ]
]

hour

hour() -> SeriesT

Extracts the hour in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the hour component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2022, 1, 1, 5, 3), datetime(2022, 1, 5, 9, 12)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.hour().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    5,
    9
  ]
]

microsecond

microsecond() -> SeriesT

Extracts the microseconds in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the microsecond component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [
...         datetime(2022, 1, 1, 5, 3, 7, 400000),
...         datetime(2022, 1, 1, 5, 3, 7, 0),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.microsecond().alias("datetime").to_native()
0    400000
1         0
Name: datetime, dtype: int32

millisecond

millisecond() -> SeriesT

Extracts the milliseconds in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the millisecond component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [
...         datetime(2022, 1, 1, 5, 3, 7, 400000),
...         datetime(2022, 1, 1, 5, 3, 7, 0),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.millisecond().alias("datetime").to_native()
0    400
1      0
Name: datetime, dtype: int32

minute

minute() -> SeriesT

Extracts the minute in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the minute component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [datetime(2022, 1, 1, 5, 3), datetime(2022, 1, 5, 9, 12)]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.minute().to_native()
0     3
1    12
dtype: int32

month

month() -> SeriesT

Gets the month in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the month component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([datetime(2012, 1, 7), datetime(2023, 3, 10)])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.month().to_native()
shape: (2,)
Series: '' [i8]
[
        1
        3
]

nanosecond

nanosecond() -> SeriesT

Extract the nanoseconds in a date series.

Returns:

Type	Description
SeriesT	A new Series containing the nanosecond component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [
...         datetime(2022, 1, 1, 5, 3, 7, 400000),
...         datetime(2022, 1, 1, 5, 3, 7, 0),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.nanosecond().alias("datetime").to_native()
0    400000000
1            0
Name: datetime, dtype: int32

offset_by

offset_by(by: str) -> SeriesT

Offset this date by a relative time offset.

Parameters:

Name	Type	Description	Default
by	str	The offset. Must be of form <multiple><unit>, where multiple is a positive integer and unit is one of 'ns': nanosecond. 'us': microsecond. 'ms': millisecond. 's': second. 'm': minute. 'h': hour. 'd': day. 'mo': month. 'q': quarter. 'y': year.	required

Returns:

Type	Description
SeriesT	Series of data type Date or Datetime.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([datetime(2021, 3, 1, 12, 34)])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.offset_by("1h").to_native()
0   2021-03-01 13:34:00
dtype: datetime64[ns]

ordinal_day

ordinal_day() -> SeriesT

Get ordinal day.

Returns:

Type	Description
SeriesT	A new Series containing the ordinal day (day of year) for each datetime value.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2020, 1, 1), datetime(2020, 8, 3)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.ordinal_day().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    1,
    216
  ]
]

replace_time_zone

replace_time_zone(time_zone: str | None) -> SeriesT

Replace time zone.

Parameters:

Name	Type	Description	Default
time_zone	str | None	Target time zone.	required

Returns:

Type	Description
SeriesT	A new Series with the specified time zone.

Examples:

>>> from datetime import datetime, timezone
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [
...         datetime(2024, 1, 1, tzinfo=timezone.utc),
...         datetime(2024, 1, 2, tzinfo=timezone.utc),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.replace_time_zone(
...     "Asia/Kathmandu"
... ).to_native()
shape: (2,)
Series: '' [datetime[μs, Asia/Kathmandu]]
[
        2024-01-01 00:00:00 +0545
        2024-01-02 00:00:00 +0545
]

second

second() -> SeriesT

Extracts the seconds in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the second component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [datetime(2022, 1, 1, 5, 3, 10), datetime(2022, 1, 5, 9, 12, 4)]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.second().to_native()
0    10
1     4
dtype: int32

timestamp

timestamp(time_unit: TimeUnit) -> SeriesT

Return a timestamp in the given time unit.

Parameters:

Name	Type	Description	Default
time_unit	TimeUnit	One of - 'ns': nanosecond. - 'us': microsecond. - 'ms': millisecond.	required

Returns:

Type	Description
SeriesT	A new Series with timestamps in the specified time unit.

Examples:

>>> from datetime import date
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [date(2001, 1, 1), None, date(2001, 1, 3)], dtype="datetime64[ns]"
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.timestamp("ms").to_native()
0    9.783072e+11
1             NaN
2    9.784800e+11
dtype: float64

total_microseconds

total_microseconds() -> SeriesT

Get total microseconds.

Returns:

Type	Description
SeriesT	A new Series containing the total number of microseconds for each timedelta value.

Notes

The function outputs the total microseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [
...         timedelta(microseconds=10),
...         timedelta(milliseconds=1, microseconds=200),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.total_microseconds().to_native()
shape: (2,)
Series: '' [i64]
[
        10
        1200
]

total_milliseconds

total_milliseconds() -> SeriesT

Get total milliseconds.

Notes

The function outputs the total milliseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Returns:

Type	Description
SeriesT	A new Series containing the total number of milliseconds for each timedelta value.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [
...         timedelta(milliseconds=10),
...         timedelta(milliseconds=20, microseconds=40),
...     ]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.total_milliseconds().to_native()
shape: (2,)
Series: '' [i64]
[
        10
        20
]

total_minutes

total_minutes() -> SeriesT

Get total minutes.

Notes

The function outputs the total minutes in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Returns:

Type	Description
SeriesT	A new Series containing the total number of minutes for each timedelta value.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [timedelta(minutes=10), timedelta(minutes=20, seconds=40)]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.total_minutes().to_native()
shape: (2,)
Series: '' [i64]
[
        10
        20
]

total_nanoseconds

total_nanoseconds() -> SeriesT

Get total nanoseconds.

Notes

The function outputs the total nanoseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Returns:

Type	Description
SeriesT	A new Series containing the total number of nanoseconds for each timedelta value.

Examples:

>>> from datetime import datetime
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     ["2024-01-01 00:00:00.000000001", "2024-01-01 00:00:00.000000002"]
... ).str.to_datetime(time_unit="ns")
>>> s = nw.from_native(s_native, series_only=True)
>>> s.diff().dt.total_nanoseconds().to_native()
shape: (2,)
Series: '' [i64]
[
        null
        1
]

total_seconds

total_seconds() -> SeriesT

Get total seconds.

Notes

The function outputs the total seconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using fill_null() in this case.

Returns:

Type	Description
SeriesT	A new Series containing the total number of seconds for each timedelta value.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(
...     [timedelta(minutes=10), timedelta(minutes=20, seconds=40)]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.total_seconds().to_native()
shape: (2,)
Series: '' [i64]
[
        600
        1240
]

to_string

to_string(format: str) -> SeriesT

Convert a Date/Time/Datetime series into a String series with the given format.

Parameters:

Name	Type	Description	Default
format	str	Format string for converting the datetime to string.	required

Returns:

Type	Description
SeriesT	A new Series with the datetime values formatted as strings according to the specified format.

Notes

Unfortunately, different libraries interpret format directives a bit differently.

• Chrono, the library used by Polars, uses "%.f" for fractional seconds, whereas pandas and Python stdlib use ".%f".
• PyArrow interprets "%S" as "seconds, including fractional seconds" whereas most other tools interpret it as "just seconds, as 2 digits".

---

Therefore, we make the following adjustments.

• for pandas-like libraries, we replace "%S.%f" with "%S%.f".
• for PyArrow, we replace "%S.%f" with "%S".

---

Workarounds like these don't make us happy, and we try to avoid them as much as possible, but here we feel like it's the best compromise.

If you just want to format a date/datetime Series as a local datetime string, and have it work as consistently as possible across libraries, we suggest using:

• "%Y-%m-%dT%H:%M:%S%.f" for datetimes
• "%Y-%m-%d" for dates

---

Though note that, even then, different tools may return a different number of trailing zeros. Nonetheless, this is probably consistent enough for most applications.

If you have an application where this is not enough, please open an issue and let us know.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2020, 3, 1), datetime(2020, 4, 1)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.to_string("%Y/%m/%d").to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    "2020/03/01",
    "2020/04/01"
  ]
]

truncate

truncate(every: str) -> SeriesT

Divide the date/datetime range into buckets.

Parameters:

Name	Type	Description	Default
every	str	Length of bucket. Must be of form <multiple><unit>, where multiple is a positive integer and unit is one of 'ns': nanosecond. 'us': microsecond. 'ms': millisecond. 's': second. 'm': minute. 'h': hour. 'd': day. 'mo': month. 'q': quarter. 'y': year.	required

Returns:

Type	Description
SeriesT	Series of data type Date or Datetime.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([datetime(2021, 3, 1, 12, 34)])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.truncate("1h").to_native()
0   2021-03-01 12:00:00
dtype: datetime64[ns]

weekday

weekday() -> SeriesT

Extract the week day in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the week day for each datetime value.
SeriesT	Returns the ISO weekday number where monday = 1 and sunday = 7

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[datetime(2020, 1, 1), datetime(2020, 8, 3)]]
... )
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.weekday().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    3,
    1
  ]
]

year

year() -> SeriesT

Get the year in a datetime series.

Returns:

Type	Description
SeriesT	A new Series containing the year component of each datetime value.

Examples:

>>> from datetime import datetime
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([datetime(2012, 1, 7), datetime(2023, 3, 10)])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.year().to_native()
shape: (2,)
Series: '' [i32]
[
        2012
        2023
]