datetime

relationalai.semantics.std.datetime

datetime(
    year: IntegerValue,
    month: IntegerValue,
    day: IntegerValue,
    hour: IntegerValue = 0,
    minute: IntegerValue = 0,
    second: IntegerValue = 0,
    millisecond: IntegerValue = 0,
    tz: dt.tzinfo | StringValue = "UTC",
)

Construct a datetime from components.

When you construct a datetime using this class, it returns an Expression and not a datetime object. All of the methods on this class are class methods that operate on datetime expressions.

Parameters

• year

  (IntegerValue) - The year.

• month

  (IntegerValue) - The month (1-12).

• day

  (IntegerValue) - The day of the month.

• hour

  (IntegerValue, default: 0) - The hour (0-23). Default: 0.

• minute

  (IntegerValue, default: 0) - The minute (0-59). Default: 0.

• second

  (IntegerValue, default: 0) - The second (0-59). Default: 0.

• millisecond

  (IntegerValue, default: 0) - The millisecond (0-999). Default: 0.

• tz

  (datetime.tzinfo | StringValue, default: “UTC”) - The timezone. Default: “UTC”.

Examples

Construct datetimes:

>>> datetime.datetime(2024, 1, 15, 14, 30, 0)
>>> datetime.datetime(2024, 1, 1, 6, 30, 45, 0, 'America/New_York')
>>> datetime.datetime(Event.year, Event.month, Event.day, Event.hour, Event.minute)

Methods

.now()

datetime.now() -> Expression

Get the current datetime.

Returns:

• Expression - An Expression computing the current datetime. Returns DateTime.

.year()

datetime.year(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Extract the year from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None (uses datetime’s timezone or UTC).

Returns:

• Expression - An Expression computing the year.

.quarter()

datetime.quarter(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Extract the quarter (1-4) from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the quarter. Returns Integer.

.month()

datetime.month(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Extract the month (1-12) from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the month. Returns Integer.

.week()

datetime.week(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Extract the ISO week number from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the week number. Returns Integer.

.day()

datetime.day(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Extract the day of the month from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the day. Returns Integer.

.dayofyear()

datetime.dayofyear(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Extract the day of the year (1-366) from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the day of year. Returns Integer.

.hour()

datetime.hour(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Extract the hour (0-23) from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the hour. Returns Integer.

.minute()

datetime.minute(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Extract the minute (0-59) from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the minute. Returns Integer.

.second()

datetime.second(datetime: DateTimeValue) -> Expression

Extract the second (0-59) from a datetime.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

Returns:

• Expression - An Expression computing the second. Returns Integer.

.isoweekday()

datetime.isoweekday(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Return the ISO weekday as an integer, where Monday is 1, and Sunday is 7.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the ISO weekday (1=Monday…7=Sunday). Returns Integer.

.weekday()

datetime.weekday(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Return the weekday as an integer, where Monday is 0, and Sunday is 6.

Parameters:

• datetime

  (DateTimeValue) - The datetime to extract from.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for extraction. Default: None.

Returns:

• Expression - An Expression computing the weekday (0=Monday…6=Sunday). Returns Integer.

.fromordinal()

datetime.fromordinal(ordinal: IntegerValue) -> Expression

Construct a datetime from a proleptic Gregorian ordinal.

Parameters:

• ordinal

  (IntegerValue) - The ordinal (day 1 is 0001-01-01).

Returns:

• Expression - An Expression computing the datetime at midnight UTC. Returns DateTime.

.strptime()

datetime.strptime(date_str: StringValue, format: str) -> Expression

Parse a datetime from a string using a format string.

Parameters:

• date_str

  (StringValue) - The datetime string to parse.

• format

  (str) - The format string. Must be a literal Python string.

Returns:

• Expression - An Expression computing the parsed datetime. Returns DateTime.

Referenced By:

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Use advanced reasoning > Rules-based reasoning
        └──  Use dates and datetimes
            └──  Parse dates and datetimes from strings

.to_date()

datetime.to_date(
    datetime: DateTimeValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Convert a datetime to a date.

Parameters:

• datetime

  (DateTimeValue) - The datetime to convert.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for conversion. Default: None.

Returns:

• Expression - An Expression computing the date. Returns Date.

.format()

datetime.format(
    date: DateTimeValue, format: StringValue, tz: dt.tzinfo | StringValue | None = None
) -> Expression

Format a datetime as a string.

Parameters:

• date

  (DateTimeValue) - The datetime to format.

• format

  (StringValue) - The format string.

• tz

  (datetime.tzinfo | StringValue | None, default: None) - The timezone for formatting. Default: None.

Returns:

• Expression - An Expression computing the formatted datetime string. Returns String.

Referenced By:

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Use advanced reasoning > Rules-based reasoning
        ├──  Work with strings
        └──  Use dates and datetimes
            └──  Format Date and DateTime values as strings

.add()

datetime.add(date: DateTimeValue, period: Variable) -> Expression

Add a period to a datetime.

Parameters:

• date

  (DateTimeValue) - The datetime to add to.

• period

  (Variable) - The period to add (use milliseconds(), seconds(), minutes(), hours(), days(), etc.).

Returns:

• Expression - An Expression computing the resulting datetime. Returns DateTime. Returns DateTime.

Examples:

Add periods to datetimes:

>>> datetime.datetime.add(Event.start_time, datetime.hours(2))
>>> datetime.datetime.add(Appointment.scheduled_at, datetime.minutes(30))
>>> datetime.datetime.add(Task.created_at, datetime.days(7))

Referenced By:

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Use advanced reasoning > Rules-based reasoning
        └──  Use dates and datetimes
            └──  Add or subtract time periods

.subtract()

datetime.subtract(date: DateTimeValue, period: Variable) -> Expression

Subtract a period from a datetime.

Parameters:

• date

  (DateTimeValue) - The datetime to subtract from.

• period

  (Variable) - The period to subtract (use milliseconds(), seconds(), minutes(), hours(), days(), etc.).

Returns:

• Expression - An Expression computing the resulting datetime. Returns DateTime.

Referenced By:

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Use advanced reasoning > Rules-based reasoning
        └──  Use dates and datetimes
            └──  Add or subtract time periods

.range()

datetime.range(
    start: DateTimeValue | None = None,
    end: DateTimeValue | None = None,
    periods: IntegerValue = 1,
    freq: Frequency = "D",
) -> Variable

Generate a range of datetimes.

Parameters:

• start

  (DateTimeValue | None, default: None) - The start datetime. If None, computes from end.

• end

  (DateTimeValue | None, default: None) - The end datetime (inclusive). If None, uses periods.

• periods

  (IntegerValue, default: 1) - Number of periods to generate. Default: 1.

• freq

  (Frequency, default: “D”) - Frequency: “ms”, “s”, “m” (minute), “H”, “D”, “W”, “M”, “Y”. Default: “D”.

Returns:

• Variable - A Variable representing the datetime range. Returns DateTime.

Raises:

• ValueError - If neither start nor end is provided.

Referenced By:

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Use advanced reasoning > Rules-based reasoning
        └──  Use dates and datetimes

.period_milliseconds()

datetime.period_milliseconds(start: DateTimeValue, end: DateTimeValue) -> Expression

Compute the number of milliseconds between two datetimes.

Parameters:

• start

  (DateTimeValue) - The start datetime.

• end

  (DateTimeValue) - The end datetime.

Returns:

• Expression - An Expression computing the number of milliseconds.

Referenced By:

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Use advanced reasoning > Rules-based reasoning
        └──  Use dates and datetimes
            └──  Compute elapsed time between two events

.diff()

datetime.diff(part: DateTimePart, start: DateTimeValue, end: DateTimeValue) -> Expression

Calculate the difference between two datetimes in the specified datetime part units.

Parameters:

• part

  (DateTimePart) - The unit to measure the difference in: “year”, “quarter”, “month”, “week”, “day”, “hour”, “minute”, “second”, or “millisecond”.

• start

  (DateTimeValue) - The start datetime.

• end

  (DateTimeValue) - The end datetime.

Returns:

• Expression - An Expression computing the difference. Returns Integer.

Examples:

Calculate datetime differences:

>>> datetime.datetime.diff("hour", Event.start_time, Event.end_time)
>>> datetime.datetime.diff("minute", Task.created_at, Task.completed_at)
>>> datetime.datetime.diff("second", Session.login_time, Session.logout_time)

Referenced By

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Use advanced reasoning > Rules-based reasoning
        ├──  Work with strings
        └──  Use dates and datetimes
            ├──  Construct Date and DateTime values
            ├──  Parse dates and datetimes from strings
            ├──  Format Date and DateTime values as strings
            ├──  Add or subtract time periods
            └──  Compute elapsed time between two events