date()#

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

Constructs a date value. If any of the year, month, or day arguments are Producer objects, then date() also acts as a filter and removes non-integer values from the producer. Must be called in a rule or query context. Alternate constructors include date.fromisoformat() 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 object.

Example#

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

#import relationalai as rai
from relationalai.std import dates


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

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


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

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

# Define people with birth_year, birth_month, and birth_day properties.
with model.rule():
    Person.add(id=2).set(name="Alice", birth_year=1990, birth_month=5, birth_day=23)
    Person.add(id=3).set(name="Carol", birth_year="invalid", birth_month=8, birth_day=15)

# Define a birth_date property using the birth year, month, and day properties.
with model.rule():
    person = Person()
    birth_date = dates.date(person.birth_year, person.birth_month, person.birth_day)
    # Since Carol's birth_year is invalid, the date() function filters her out
    # and the following only sets the birth_date property for Alice.
    person.set(birth_date=birth_date)
    # The following only sets the has_valid date property for Alice.
    person.set(has_valid_date=True)

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

print(response.results)
#     name birth_date has_valid_date
# 0  Alice 1990-05-23           True
# 1    Bob 2021-01-01            NaN
# 2  Carol        NaT            NaN

Use the + and - operators to add or subtract time periods, like days() and months() from date values:

#from relationalai.std import alias

# Add 7 days to each person's birth date.
with model.query() as select:
    person = Person()
    new_date = person.birth_date + dates.days(7)
    response = select(person.name, person.birth_date, alias(new_date, "new_date"))

print(response.results)
#     name birth_date   new_date
# 0  Alice 1990-05-23 1990-05-30
# 1    Bob 2021-01-01 2021-01-08

# Subtract 1 month from each person's birth date.
with model.query() as select:
    person = Person()
    new_date = person.birth_date - dates.months(1)
    response = select(person.name, person.birth_date, alias(new_date, "new_date"))

print(response.results)
#     name birth_date   new_date
# 0  Alice 1990-05-23 1990-04-23
# 1    Bob 2021-01-01 2020-12-01

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

#with model.query() as select:
    person1, person2 = Person(), Person()
    person1.birth_date > person2.birth_date
    difference = person1.birth_date - person2.birth_date
    response = select(person1.name, person2.name, alias(difference, "difference"))

print(response.results)
#   name  name2  difference
# 0  Bob  Alice       11181

Keep in mind that the difference between two dates is not an integer. In particular, you can’t do arithmetic on the difference directly. For example, if you want to divide the difference between two dates by 365 to get the number of years between them, you must first extract the integer value from the period as follows:

#from relationalai.std import create_var

with model.query() as select:
    person1, person2 = Person(), Person()
    person1.birth_date > person2.birth_date
    # Get the integer difference in days between the two dates.
    diff_days = create_var()
    days(diff_days) == person1.birth_date - person2.birth_date
    # Convert the difference in days to years.
    diff_years = diff_days / 365
    response = select(person1.name, person2.name, alias(diff_years, "diff_years"))

print(response.results)
#   name  name2  diff_years
# 0  Bob  Alice   30.632877

You can extract parts of date values using functions like year() and month():

#from relationalai.std.dates import year, month, day

with model.query() as select:
    person = Person()
    response = select(
        person.name,
        alias(dates.year(person.birth_date), "birth_year"),
        alias(dates.month(person.birth_date), "birth_month"),
    )

print(response.results)
#     name  birth_year  birth_month
# 0  Alice        1990            5
# 1    Bob        2021            1

See Also#