date()#

relationalai.std.dates
#date(
    year: int | Producer,
    month: int | Producer,
    day: int | Producer
) -> Expression

Constructs a Date value. Must be called in a rule or query context. Alternate constructors include date.fromordinal() and date.fromdatetime(). To construct a DateTime value, use the datetime() function.

Parameters#

NameTypeDescription
yearint or ProducerThe year component.
monthint or ProducerThe month component.
dayint or ProducerThe day component.

Returns#

An Expression that produces Date values.

Example#

Use date() to construct a Date value by specifying the year, month, and day components:

#import relationalai as rai
from relationalai.std.dates import date

# Create a model named "people" with a `Person` type.
model = rai.Model("people")
Person = model.Type("Person")

# Add a person with a birth date.
with model.rule():
    # Bob was born on January 1, 2021.
    Person.add(name="Bob", birth_date=date(2021, 1, 1))

with model.query() as select:
    person = Person()
    response = select(person.name, person.birth_date)

print(response.results)
# Output:
#   name birth_date
# 0  Bob 2021-01-01

You can construct dates using object property values instead of literal values:

#import relationalai as rai
from relationalai.std.dates import date

# Create a model named "people" with a `Person` type.
model = rai.Model("people")
Person = model.Type("Person")

# Add people with birth year, month, and day.
with model.rule():
    Person.add(
        name="Alice",
        birth_year=1990,
        birth_month=5,
        birth_day=23
    )
    Person.add(
        name="Bob",
        birth_year=1985,
        birth_month=8,
        birth_day=15
    )

# Create a `birth_date` property using the `date` constructor.
with model.rule():
    person = Person()
    person.set(
        birth_date=date(person.birth_year, person.birth_month, person.birth_day)
    )

with model.query() as select:
    person = Person()
    response = select(person.name, person.birth_date)

print(response.results)
# Output:
#     name birth_date
# 0  Alice 1990-05-23
# 1    Bob 1985-08-15

To manipulate dates, use the + and - operators to add or subtract time periods:

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

# Create a model named "events" with an `Event` type.
model = rai.Model("events")
Event = model.Type("Event")

# Add an event with a start date.
with model.rule():
    # The event starts on January 1, 2021.
    Event.add(name="Conference", start_date=date(2021, 1, 1))

# Add 7 days to the event start date.
with model.query() as select:
    event = Event(name="Conference")
    new_date = event.start_date + days(7)
    response = select(event.name, alias(new_date, "new_date"))

print(response.results)
# Output:
#          name   new_date
# 0  Conference 2021-01-08

The difference between two dates can be calculated using the - operator and is returned as a period of days():

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

# Create a model named "events" with an `Event` type.
model = rai.Model("events")
Event = model.Type("Event")

# Add two events with start dates.
with model.rule():
    # The first event starts on January 1, 2021.
    event1 = Event.add(name="Conference", start_date=date(2021, 1, 1))
    # The second event starts on January 8, 2021.
    event2 = Event.add(name="Workshop", start_date=date(2021, 1, 8))

# Calculate the difference between the two start dates.
with model.query() as select:
    event1 = Event(name="Conference")
    event2 = Event(name="Workshop")
    difference = event2.start_date - event1.start_date
    response = select(event1.name, event2.name, alias(difference, "difference"))

print(response.results)
# Output:
#          name     name2  difference
# 0  Conference  Workshop           7

# NOTE: The difference is a period denominated in days, not an integer.
with model.query() as select:
    event1 = Event(name="Conference")
    event2 = Event(name="Workshop")
    # The following fails because the difference is not an integer.
    event2.start_date - event1.start_date == 7
    response = select(event1.name, event2.name)

print(response.results)
# Output:
# Empty DataFrame
# Columns: []
# Index: []

# Use the `days()` function to compare the difference.
with model.query() as select:
    event1 = Event(name="Conference")
    event2 = Event(name="Workshop")
    # The following succeeds.
    event2.start_date - event1.start_date == days(7)
    response = select(event1.name, event2.name)

print(response.results)
# Output:
#          name     name2
# 0  Conference  Workshop

Parts of Date values may be extracted using functions like year(), month(), and day():

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

# Create a model named "people" with a `Person` type.
model = rai.Model("people")
Person = model.Type("Person")

# Add a person with a birth date.
with model.rule():
    Person.add(name="Bob", birth_date=date(2021, 1, 1))

# Extract the year from the `birth_date`.
with model.query() as select:
    person = Person()
    birth_year = year(person.birth_date)
    response = select(person.name, alias(birth_year, "birth_year"))

print(response.results)
# Output:
#   name  birth_year
# 0  Bob        2021

Use the date_range() function to create various ranges of dates:

#import relationalai as rai
from relationalai.std.dates import date, date_range

model = rai.Model("dates")

# Create a range of dates from January 1, 2024, to January 7, 2024.
with model.query() as select:
    dates = date_range(date(2024, 1, 1), date(2024, 1, 7))
    response = select(dates)

print(response.results)
# Output:
#            v
# 0 2024-01-01
# 1 2024-01-02
# 2 2024-01-03
# 3 2024-01-04
# 4 2024-01-05
# 5 2024-01-06
# 6 2024-01-07

See date_range() for details.

See Also#