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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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

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.

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.

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.

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.

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.

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

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 pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([datetime(2020, 3, 1), datetime(2020, 4, 1)])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.dt.to_string("%Y/%m/%d")
┌───────────────┐
|Narwhals Series|
|---------------|
|0    2020/03/01|
|1    2020/04/01|
|dtype: object  |
└───────────────┘

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

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.

Note that 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.

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
]