narwhals.Expr.dt

convert_time_zone

convert_time_zone(time_zone: str) -> ExprT

Convert to a new 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
ExprT	A new expression.

Examples:

>>> from datetime import datetime, timezone
>>> import pandas as pd
>>> import narwhals as nw
>>> df_native = pd.DataFrame(
...     {
...         "a": [
...             datetime(2024, 1, 1, tzinfo=timezone.utc),
...             datetime(2024, 1, 2, tzinfo=timezone.utc),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.select(nw.col("a").dt.convert_time_zone("Asia/Kathmandu")).to_native()
                          a
0 2024-01-01 05:45:00+05:45
1 2024-01-02 05:45:00+05:45

date

date() -> ExprT

Extract the date from underlying DateTime representation.

Returns:

Type	Description
ExprT	A new expression.

Raises:

Type	Description
NotImplementedError	If pandas default backend is being used.

Examples:

>>> from datetime import datetime
>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame(
...     {"a": [datetime(2012, 1, 7, 10), datetime(2027, 12, 13)]}
... )
>>> df = nw.from_native(df_native)
>>> df.select(nw.col("a").dt.date()).to_native()
shape: (2, 1)
┌────────────┐
│ a          │
│ ---        │
│ date       │
╞════════════╡
│ 2012-01-07 │
│ 2027-12-13 │
└────────────┘

day

day() -> ExprT

Extract day from underlying DateTime representation.

Returns the day of month starting from 1. The return value ranges from 1 to 31. (The last day of month differs by months.)

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> df_native = pa.table({"a": [datetime(1978, 6, 1), datetime(2065, 1, 1)]})
>>> df = nw.from_native(df_native)
>>> df.with_columns(nw.col("a").dt.day().alias("day")).to_native()
pyarrow.Table
a: timestamp[us]
day: int64
----
a: [[1978-06-01 00:00:00.000000,2065-01-01 00:00:00.000000]]
day: [[1,1]]

hour

hour() -> ExprT

Extract hour from underlying DateTime representation.

Returns the hour number from 0 to 23.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame(
...     {"a": [datetime(1978, 1, 1, 1), datetime(2065, 1, 1, 10)]}
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(nw.col("a").dt.hour().alias("hour"))
┌──────────────────────────────┐
|      Narwhals DataFrame      |
|------------------------------|
|shape: (2, 2)                 |
|┌─────────────────────┬──────┐|
|│ a                   ┆ hour │|
|│ ---                 ┆ ---  │|
|│ datetime[μs]        ┆ i8   │|
|╞═════════════════════╪══════╡|
|│ 1978-01-01 01:00:00 ┆ 1    │|
|│ 2065-01-01 10:00:00 ┆ 10   │|
|└─────────────────────┴──────┘|
└──────────────────────────────┘

microsecond

microsecond() -> ExprT

Extract microseconds from underlying DateTime representation.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> df_native = pa.table(
...     {
...         "a": [
...             datetime(1978, 1, 1, 1, 1, 1, 0),
...             datetime(2065, 1, 1, 10, 20, 30, 67000),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(
...     nw.col("a").dt.microsecond().alias("microsecond")
... ).to_native()
pyarrow.Table
a: timestamp[us]
microsecond: int64
----
a: [[1978-01-01 01:01:01.000000,2065-01-01 10:20:30.067000]]
microsecond: [[0,67000]]

millisecond

millisecond() -> ExprT

Extract milliseconds from underlying DateTime representation.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> df_native = pa.table(
...     {
...         "a": [
...             datetime(1978, 1, 1, 1, 1, 1, 0),
...             datetime(2065, 1, 1, 10, 20, 30, 67000),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(
...     nw.col("a").dt.millisecond().alias("millisecond")
... ).to_native()
pyarrow.Table
a: timestamp[us]
millisecond: int64
----
a: [[1978-01-01 01:01:01.000000,2065-01-01 10:20:30.067000]]
millisecond: [[0,67]]

minute

minute() -> ExprT

Extract minutes from underlying DateTime representation.

Returns the minute number from 0 to 59.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> df_native = pd.DataFrame(
...     {"a": [datetime(1978, 1, 1, 1, 1), datetime(2065, 1, 1, 10, 20)]}
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(nw.col("a").dt.minute().alias("minute")).to_native()
                    a  minute
0 1978-01-01 01:01:00       1
1 2065-01-01 10:20:00      20

month

month() -> ExprT

Extract month from underlying DateTime representation.

Returns the month number starting from 1. The return value ranges from 1 to 12.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> df_native = pa.table({"a": [datetime(1978, 6, 1), datetime(2065, 1, 1)]})
>>> df = nw.from_native(df_native)
>>> df.with_columns(nw.col("a").dt.month().alias("month")).to_native()
pyarrow.Table
a: timestamp[us]
month: int64
----
a: [[1978-06-01 00:00:00.000000,2065-01-01 00:00:00.000000]]
month: [[6,1]]

nanosecond

nanosecond() -> ExprT

Extract Nanoseconds from underlying DateTime representation.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> df_native = pa.table(
...     {
...         "a": [
...             datetime(1978, 1, 1, 1, 1, 1, 0),
...             datetime(2065, 1, 1, 10, 20, 30, 67000),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(
...     nw.col("a").dt.nanosecond().alias("nanosecond")
... ).to_native()
pyarrow.Table
a: timestamp[us]
nanosecond: int64
----
a: [[1978-01-01 01:01:01.000000,2065-01-01 10:20:30.067000]]
nanosecond: [[0,67000000]]

ordinal_day

ordinal_day() -> ExprT

Get ordinal day.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> df_native = pd.DataFrame(
...     {"a": [datetime(2020, 1, 1), datetime(2020, 8, 3)]}
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(a_ordinal_day=nw.col("a").dt.ordinal_day())
┌───────────────────────────┐
|    Narwhals DataFrame     |
|---------------------------|
|           a  a_ordinal_day|
|0 2020-01-01              1|
|1 2020-08-03            216|
└───────────────────────────┘

replace_time_zone

replace_time_zone(time_zone: str | None) -> ExprT

Replace time zone.

Parameters:

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

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime, timezone
>>> import pandas as pd
>>> import narwhals as nw
>>> df_native = pd.DataFrame(
...     {
...         "a": [
...             datetime(2024, 1, 1, tzinfo=timezone.utc),
...             datetime(2024, 1, 2, tzinfo=timezone.utc),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.select(nw.col("a").dt.replace_time_zone("Asia/Kathmandu")).to_native()
                          a
0 2024-01-01 00:00:00+05:45
1 2024-01-02 00:00:00+05:45

second

second() -> ExprT

Extract seconds from underlying DateTime representation.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pyarrow as pa
>>> import narwhals as nw
>>> df_native = pa.table(
...     {
...         "a": [
...             datetime(1978, 1, 1, 1, 1, 1),
...             datetime(2065, 1, 1, 10, 20, 30),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(nw.col("a").dt.second().alias("second")).to_native()
pyarrow.Table
a: timestamp[us]
second: int64
----
a: [[1978-01-01 01:01:01.000000,2065-01-01 10:20:30.000000]]
second: [[1,30]]

timestamp

timestamp(time_unit: TimeUnit = 'us') -> ExprT

Return a timestamp in the given time unit.

Parameters:

Name	Type	Description	Default
time_unit	TimeUnit	{'ns', 'us', 'ms'} Time unit.	'us'

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import date
>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame({"date": [date(2001, 1, 1), None]})
>>> df = nw.from_native(df_native)
>>> df.with_columns(nw.col("date").dt.timestamp("ms").alias("timestamp_ms"))
┌─────────────────────────────┐
|     Narwhals DataFrame      |
|-----------------------------|
|shape: (2, 2)                |
|┌────────────┬──────────────┐|
|│ date       ┆ timestamp_ms │|
|│ ---        ┆ ---          │|
|│ date       ┆ i64          │|
|╞════════════╪══════════════╡|
|│ 2001-01-01 ┆ 978307200000 │|
|│ null       ┆ null         │|
|└────────────┴──────────────┘|
└─────────────────────────────┘

total_microseconds

total_microseconds() -> ExprT

Get total microseconds.

Returns:

Type	Description
ExprT	A new expression.

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() and cast in this case.

Examples:

>>> from datetime import timedelta
>>> import pyarrow as pa
>>> import narwhals as nw
>>> df_native = pa.table(
...     {
...         "a": [
...             timedelta(microseconds=10),
...             timedelta(milliseconds=1, microseconds=200),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(
...     a_total_microseconds=nw.col("a").dt.total_microseconds()
... ).to_native()
pyarrow.Table
a: duration[us]
a_total_microseconds: int64
----
a: [[10,1200]]
a_total_microseconds: [[10,1200]]

total_milliseconds

total_milliseconds() -> ExprT

Get total milliseconds.

Returns:

Type	Description
ExprT	A new expression.

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() and cast in this case.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame(
...     {
...         "a": [
...             timedelta(milliseconds=10),
...             timedelta(milliseconds=20, microseconds=40),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(
...     a_total_milliseconds=nw.col("a").dt.total_milliseconds()
... ).to_native()
shape: (2, 2)
┌──────────────┬──────────────────────┐
│ a            ┆ a_total_milliseconds │
│ ---          ┆ ---                  │
│ duration[μs] ┆ i64                  │
╞══════════════╪══════════════════════╡
│ 10ms         ┆ 10                   │
│ 20040µs      ┆ 20                   │
└──────────────┴──────────────────────┘

total_minutes

total_minutes() -> ExprT

Get total minutes.

Returns:

Type	Description
ExprT	A new expression.

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() and cast in this case.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame(
...     {"a": [timedelta(minutes=10), timedelta(minutes=20, seconds=40)]}
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(
...     a_total_minutes=nw.col("a").dt.total_minutes()
... ).to_native()
shape: (2, 2)
┌──────────────┬─────────────────┐
│ a            ┆ a_total_minutes │
│ ---          ┆ ---             │
│ duration[μs] ┆ i64             │
╞══════════════╪═════════════════╡
│ 10m          ┆ 10              │
│ 20m 40s      ┆ 20              │
└──────────────┴─────────────────┘

total_nanoseconds

total_nanoseconds() -> ExprT

Get total nanoseconds.

Returns:

Type	Description
ExprT	A new expression.

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() and cast in this case.

Examples:

>>> from datetime import timedelta
>>> import pandas as pd
>>> import narwhals as nw
>>> df_native = pd.DataFrame(
...     {
...         "a": pd.to_datetime(
...             [
...                 "2024-01-01 00:00:00.000000001",
...                 "2024-01-01 00:00:00.000000002",
...             ]
...         )
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(
...     a_diff_total_nanoseconds=nw.col("a").diff().dt.total_nanoseconds()
... ).to_native()
                              a  a_diff_total_nanoseconds
0 2024-01-01 00:00:00.000000001                       NaN
1 2024-01-01 00:00:00.000000002                       1.0

total_seconds

total_seconds() -> ExprT

Get total seconds.

Returns:

Type	Description
ExprT	A new expression.

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() and cast in this case.

Examples:

>>> from datetime import timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame(
...     {"a": [timedelta(seconds=10), timedelta(seconds=20, milliseconds=40)]}
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(
...     a_total_seconds=nw.col("a").dt.total_seconds()
... ).to_native()
shape: (2, 2)
┌──────────────┬─────────────────┐
│ a            ┆ a_total_seconds │
│ ---          ┆ ---             │
│ duration[μs] ┆ i64             │
╞══════════════╪═════════════════╡
│ 10s          ┆ 10              │
│ 20s 40ms     ┆ 20              │
└──────────────┴─────────────────┘

to_string

to_string(format: str) -> ExprT

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

Parameters:

Name	Type	Description	Default
format	str	Format to format temporal column with.	required

Returns:

Type	Description
ExprT	A new expression.

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 polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame(
...     {
...         "a": [
...             datetime(2020, 3, 1),
...             datetime(2020, 5, 1),
...         ]
...     }
... )
>>> df = nw.from_native(df_native)
>>> df.select(nw.col("a").dt.to_string("%Y/%m/%d %H:%M:%S"))
┌───────────────────────┐
|  Narwhals DataFrame   |
|-----------------------|
|shape: (2, 1)          |
|┌─────────────────────┐|
|│ a                   │|
|│ ---                 │|
|│ str                 │|
|╞═════════════════════╡|
|│ 2020/03/01 00:00:00 │|
|│ 2020/05/01 00:00:00 │|
|└─────────────────────┘|
└───────────────────────┘

weekday

weekday() -> ExprT

Extract the week day from the underlying Date representation.

Returns:

Type	Description
ExprT	Returns the ISO weekday number where monday = 1 and sunday = 7

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> df_native = pd.DataFrame(
...     {"a": [datetime(2020, 1, 1), datetime(2020, 8, 3)]}
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(a_week_day=nw.col("a").dt.weekday())
┌────────────────────────┐
|   Narwhals DataFrame   |
|------------------------|
|           a  a_week_day|
|0 2020-01-01           3|
|1 2020-08-03           1|
└────────────────────────┘

year

year() -> ExprT

Extract year from underlying DateTime representation.

Returns the year number in the calendar date.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> from datetime import datetime
>>> import pandas as pd
>>> import narwhals as nw
>>> df_native = pd.DataFrame(
...     {"a": [datetime(1978, 6, 1), datetime(2065, 1, 1)]}
... )
>>> df = nw.from_native(df_native)
>>> df.with_columns(nw.col("a").dt.year().alias("year"))
┌──────────────────┐
|Narwhals DataFrame|
|------------------|
|           a  year|
|0 1978-06-01  1978|
|1 2065-01-01  2065|
└──────────────────┘