relationalai.std.dates.date_add()
date_add()
Section titled “date_add()”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
Section titled “Parameters”Name | Type | Description |
---|---|---|
date | Producer or Python date or datetime | The date or datetime value to which to add the period. |
period | Producer | The time period to add to the date. May be one of: |
Returns
Section titled “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
Section titled “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 raifrom 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