date()#
#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#
Name | Type | Description |
---|---|---|
year | int or Producer | The year component. |
month | int or Producer | The month component. |
day | int or Producer | The 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.