date_add()#

relationalai.std.dates
#date_add(
    date: date|datetime|Producer,
    period: Producer
) -> Expression

Adds a time period to a date or datetime value. Same as using the + operator with a period constructor. That is, date_add(date, period) is equivalent to date + period. If date or period is a Producer, then date_add() also acts as a filter and removes invalid values from the producer. In particular, if period is sub-day, then any date values produced by date are filtered out and the addition is only performed on datetime values. Must be called in a rule or query context.

Parameters#

NameTypeDescription
dateProducer or Python date or datetimeThe date or datetime value to which to add the period.
periodProducerThe time period to add to the date. May be one of:

Returns#

An Expression object. If date is a date value and period is one of years(), months(), or days(), then the Expression produces date values. If date is a datetime value, then the Expression produces datetime values.

Example#

You can use date_add() to add a time period to a date or datetime value. Typically, however, you use the + operator instead of calling date_add() directly:

#import relationalai as rai
from relationalai.std import alias, dates


# =====
# SETUP
# =====

model = rai.Model("MyModel")
Event = model.Type("Event")

with model.rule():
    Event.add(id=1).set(start=dates.datetime(2021, 1, 1, 9, 30), duration=dates.hours(1))
    Event.add(id=2).set(start=dates.date(2021, 2, 1), duration=dates.days(1))
    Event.add(id=3).set(start=dates.date(2021, 3, 1), duration=dates.hours(1))


# =======
# EXAMPLE
# =======

with model.rule():
    event = Event()
    # date_add() filters out any events with invalid start or duration values.
    # Event 3 has a date start value and a sub-day duration, so the following
    # only sets the end property for Events 1 and 2.
    event.set(end=event.start + event.duration)
    # Since Event 3 is filtered above, the following only sets the
    # has_valid_start_and_duration property for Events 1 and 2.
    event.set(has_valid_start_and_duration=True)

with model.query() as select:
    event = Event()
    response = select(event.id, event.end, event.has_valid_start_and_duration)

print(response.results)
#   id                 end has_valid_start_and_duration
# 0   1 2021-01-01 10:30:00                         True
# 1   2 2021-02-02 00:00:00                         True
# 2   3                 NaT                          NaN

If you need to add a sub-day time period to a date, you can use datetime.fromdate() to convert the date to a datetime value before adding the period:

## Alternative version of the rule in the preceding example that converts any date
# values produced by event.start to datetime values before adding the duration.
with model.rule():
    event = Event()
    with model.match():
        # If event.start is a date, convert it to a datetime before adding the duration.
        with model.case():
            dates.Date(event.start)
            date_as_time = dates.datetime.fromdate(event.start)
            event.set(end=date_as_time + event.duration)
        # Otherwise, add the duration without conversion.
        with model.case():
            event.set(end=event.start + event.duration)

with model.query() as select:
    event = Event()
    response = select(event.id, event.end)

print(response.results)
#    id                 end
# 0   1 2021-01-01 10:30:00
# 1   2 2021-02-02 00:00:00
# 2   3 2021-03-01 01:00:00

See Also#