datetime()#
#datetime(
year: int | Producer,
month: int | Producer,
day: int | Producer,
hour: int | Producer = 0,
minute: int | Producer = 0,
second: int | Producer = 0,
millisecond: int | Producer = 0,
tz: datetime.tzinfo | str | Producer = "UTC"
) -> Expression
Constructs a DateTime
value.
Must be called in a rule or query context.
Alternate constructors include datetime.fromordinal()
and datetime.fromdate()
.
To construct a Date
value, use the date()
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. |
hour | int or Producer | Optional hour component (default is 0). |
minute | int or Producer | Optional minute component (default is 0). |
second | int or Producer | Optional second component (default is 0). |
millisecond | int or Producer | Optional millisecond component (default is 0). |
tz | tzinfo or str or Producer | Optional timezone component (default is “UTC”). |
Returns#
An Expression
that produces DateTime
values.
Example#
Use datetime()
to construct a DateTime
value by specifying the year, month, day, hour, minute, second, millisecond, and timezone components:
#import relationalai as rai
from relationalai.std.dates import datetime
# Create a model named "people" with a `Person` type.
model = rai.Model("people")
Person = model.Type("Person")
# Add a person with a birth date and time.
with model.rule():
# Bob was born on January 1, 2021, at 12:00 PM UTC.
Person.add(
name="Bob",
born_at=datetime(2021, 1, 1, 12, 0, 0, tz="UTC"))
with model.query() as select:
person = Person()
response = select(person.name, person.born_at)
print(response.results)
# Output:
# name born_at
# 0 Bob 2021-01-01 12:00:00
You can construct DateTime
values using object property values instead of literal values:
#import relationalai as rai
from relationalai.std.dates import datetime
# Create a model named "people" with a `Person` type.
model = rai.Model("people")
Person = model.Type("Person")
# Add people with birth date and time components.
with model.rule():
Person.add(
name="Alice",
birth_year=1990,
birth_month=5,
birth_day=23,
birth_hour=10,
birth_minute=30,
birth_second=45
)
Person.add(
name="Bob",
birth_year=1985,
birth_month=8,
birth_day=15,
birth_hour=15,
birth_minute=45,
birth_second=0
)
# Create a born_at property using the datetime constructor.
with model.rule():
person = Person()
person.set(
born_at=datetime(
person.birth_year,
person.birth_month,
person.birth_day,
person.birth_hour,
person.birth_minute,
person.birth_second
)
)
with model.query() as select:
person = Person()
response = select(person.name, person.born_at)
print(response.results)
# Output:
# name born_at
# 0 Alice 1990-05-23 10:30:45
# 1 Bob 1985-08-15 15:45:00
To manipulate datetimes, you can use the +
and -
operators to add or subtract time periods:
#import relationalai as rai
from relationalai.std import alias
from relationalai.std.dates import datetime, days
# Create a model named "events" with an `Event` type.
model = rai.Model("events")
Event = model.Type("Event")
# Add an event with a start datetime.
with model.rule():
# The event starts on January 1, 2021, at 12:00 PM UTC.
Event.add(
name="Conference",
starts_at=datetime(2021, 1, 1, 12, 0, 0, tz="UTC"))
# Add 7 days to the event start datetime.
with model.query() as select:
event = Event(name="Conference")
new_datetime = event.starts_at + days(7)
response = select(event.name, alias(new_datetime, "new_time"))
print(response.results)
# Output:
# name new_time
# 0 Conference 2021-01-08 12:00:00
The difference between two datetimes can be calculated using the -
operator
and is returned as a period of nanoseconds
:
#import relationalai as rai
from relationalai.std import alias
from relationalai.std.dates import datetime, nanoseconds
# Create a model named "events" with an `Event` type.
model = rai.Model("events")
Event = model.Type("Event")
# Add two events with start datetimes.
with model.rule():
# The first event starts on January 1, 2021, at 12:00 PM UTC.
event1 = Event.add(
name="Conference",
starts_at=datetime(2021, 1, 1, 12, 0, 0, tz="UTC")
)
# The second event starts on January 1, 2021, at 12:00:00.000000750 PM UTC.
event2 = Event.add(
name="Workshop",
starts_at=datetime(2021, 1, 1, 12, 0, 0, 0, 0, 750, tz="UTC")
)
# Calculate the difference between the two start datetimes.
with model.query() as select:
event1 = Event(name="Conference")
event2 = Event(name="Workshop")
difference = event2.starts_at - event1.starts_at
response = select(event1.name, event2.name, alias(difference, "difference"))
print(response.results)
# Output:
# name name2 difference
# 0 Conference Workshop 750
# NOTE: The difference is a period denominated in nanoseconds,
# 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.starts_at - event1.starts_at == 750
response = select(event1.name, event2.name)
print(response.results)
# Output:
# Empty DataFrame
# Columns: []
# Index: []
# Use the 'nanoseconds()' function to compare the difference.
with model.query() as select:
event1 = Event(name="Conference")
event2 = Event(name="Workshop")
# The following succeeds.
event2.starts_at - event1.starts_at == nanoseconds(750)
response = select(event1.name, event2.name)
print(response.results)
# Output:
# name name2
# 0 Conference Workshop
You can also extract parts of DateTime
values using functions like year()
, month()
, day()
, hour()
, minute()
, and second()
:
#import relationalai as rai
from relationalai.std.dates import datetime, hour
from relationalai.std import alias
# Create a model named "people" with a `Person` type.
model = rai.Model("people")
Person = model.Type("Person")
# Add a person with a birth datetime.
with model.rule():
Person.add(
name="Bob",
born_at=datetime(1985, 8, 15, 15, 45, 0, tz="UTC")
)
# Extract the hour from the birth datetime.
with model.query() as select:
person = Person()
birth_hour = hour(person.born_at)
response = select(person.name, alias(birth_hour, "birth_hour"))
print(response.results)
# Output:
# name birth_hour
# 0 Bob 15
Use the date_range()
function to create various ranges of datetimes:
#import relationalai as rai
from relationalai.std.dates import datetime, date_range
model = rai.Model("dates")
# Create a range of datetimes from January 1, 2024, to January 1, 2024, with an hourly frequency.
with model.query() as select:
times = date_range(
datetime(2024, 1, 1, 0, 0, 0),
datetime(2024, 1, 1, 12, 0, 0),
freq="H"
)
response = select(times)
print(response.results)
# Output:
# v
# 0 2024-01-01 00:00:00
# 1 2024-01-01 01:00:00
# 2 2024-01-01 02:00:00
# 3 2024-01-01 03:00:00
# 4 2024-01-01 04:00:00
# 5 2024-01-01 05:00:00
# 6 2024-01-01 06:00:00
# 7 2024-01-01 07:00:00
# 8 2024-01-01 08:00:00
# 9 2024-01-01 09:00:00
# 10 2024-01-01 10:00:00
# 11 2024-01-01 11:00:00
# 12 2024-01-01 12:00:00
See date_range()
for details.