[Enh]: Add Expr.dt.offset_by()

We would like to learn about your use case. For example, if this feature is needed to adopt Narwhals in an open source project, could you please enter the link to it below?

No response

Please describe the purpose of the new feature or describe the problem to solve.

It would be nice to have a method to subtract and add periods from date and datetime columns. My use case for this is calculating year over year change by self joining a dataframe on month = previous year month. However, there are many other use cases for this when working with timeseries data.

Suggest a solution if possible.

No response

If you have tried alternatives, please describe them below.

I couldn't find a good alternative.

Additional information that may help us understand your needs.

No response

@denisdlugach

thanks @denisdlugach for the request!

we should definitely add this, but with the same restriction that we have in dt.truncate, that is to say: that we accept durations of the form , and not combinations of them. E.g.:

dt.offset_by('1mo') is valid
dt.offset_by('1mo2d3h') is not

Agreed #2573 (comment)

Another important note: '1d' should behave like one calendar day, not like '24h'.

Fortunately, duckdb and Polars do this by default:

In [22]: rel = duckdb.sql("""select * from values (timestamptz '2020-10-25') df(a)""")

In [23]: rel
Out[23]:
┌──────────────────────────┐
│            a             │
│ timestamp with time zone │
├──────────────────────────┤
│ 2020-10-25 00:00:00+02   │
└──────────────────────────┘

In [24]: duckdb.sql("""select date_add('1 day', "a") from rel""")
Out[24]:
┌──────────────────────────┐
│   date_add('1 day', a)   │
│ timestamp with time zone │
├──────────────────────────┤
│ 2020-10-26 00:00:00+01   │
└──────────────────────────┘

but for pandas, IIRC, the behaviour changes between version 2 and 3. We'd need to find a way to make sure we're always adding 1 calendar day

@MarcoGorelli

but for pandas, IIRC, the behaviour changes between version 2 and 3. We'd need to find a way to make sure we're always adding 1 calendar day

@MarcoGorelli would pandas.tseries.offsets be stable across versions for this behavior? (e.g. pandas.tseries.offsets.Day).

nope 😭

@MarcoGorelli

@MarcoGorelli would pandas.tseries.offsets be stable across versions for this behavior? (e.g. pandas.tseries.offsets.Day).

what you could do for pandas, though, is:

remove the timezone (dt.tz_localize(None))
apply pandas.tseries.offsets.Day
put the timezone back (dt.tz_localize(original_time_zone))

i think that should work?

I started working on it, will try to put some draft soon

@raisadz

@raisadz @MarcoGorelli was there plan to support negative offsets? Eg. "-12mo"?

@denisdlugach

Thanks for the request @denisdlugach , I am working on a PR to add negative offsets

Navigation Menu

Repository navigation

[Enh]: Add Expr.dt.offset_by() #2573

We would like to learn about your use case. For example, if this feature is needed to adopt Narwhals in an open source project, could you please enter the link to it below?

Please describe the purpose of the new feature or describe the problem to solve.

Suggest a solution if possible.

If you have tried alternatives, please describe them below.

Additional information that may help us understand your needs.

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Enh]: Add Expr.dt.offset_by() #2573

Description

We would like to learn about your use case. For example, if this feature is needed to adopt Narwhals in an open source project, could you please enter the link to it below?

Please describe the purpose of the new feature or describe the problem to solve.

Suggest a solution if possible.

If you have tried alternatives, please describe them below.

Additional information that may help us understand your needs.

Activity

MarcoGorelli commented on May 18, 2025

dangotbanned commented on May 18, 2025

MarcoGorelli commented on May 19, 2025

camriddell commented on May 19, 2025

MarcoGorelli commented on May 19, 2025

MarcoGorelli commented on Jun 23, 2025

raisadz commented on Jun 25, 2025

denisdlugach commented on Jul 9, 2025

raisadz commented on Jul 14, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions