datetime()#

relationalai.std.dates

#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.

datetime()#

Parameters#

Returns#

Example#

See Also#