date

relationalai.semantics.std.datetime

date(year: IntegerValue, month: IntegerValue, day: IntegerValue)

Construct a date from year, month, and day.

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

Parameters

• year

  (IntegerValue) - The year.

• month

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

• day

  (IntegerValue) - The day of the month.

Examples

Construct dates:

>>> datetime.date(2024, 1, 15)
>>> datetime.date(Employee.hire_year, Employee.hire_month, Employee.hire_day)

Methods

.year()

date.year(date: DateValue) -> Expression

Extract the year from a date.

Parameters:

• date

  (DateValue) - The date to extract from.

Returns:

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

Examples:

Extract year from dates:

>>> datetime.date.year(Event.start_date)
>>> select(Person.name).where(datetime.date.year(Person.birth_date) == 2000)

.quarter()

date.quarter(date: DateValue) -> Expression

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

Parameters:

• date

  (DateValue) - The date to extract from.

Returns:

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

.month()

date.month(date: DateValue) -> Expression

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

Parameters:

• date

  (DateValue) - The date to extract from.

Returns:

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

.week()

date.week(date: DateValue) -> Expression

Extract the ISO week number from a date.

Parameters:

• date

  (DateValue) - The date to extract from.

Returns:

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

.day()

date.day(date: DateValue) -> Expression

Extract the day of the month from a date.

Parameters:

• date

  (DateValue) - The date to extract from.

Returns:

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

.dayofyear()

date.dayofyear(date: DateValue) -> Expression

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

Parameters:

• date

  (DateValue) - The date to extract from.

Returns:

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

.isoweekday()

date.isoweekday(date: DateValue) -> Expression

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

Parameters:

• date

  (DateValue) - The date to extract from.

Returns:

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

.weekday()

date.weekday(date: DateValue) -> Expression

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

Parameters:

• date

  (DateValue) - The date to extract from.

Returns:

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

.fromordinal()

date.fromordinal(ordinal: IntegerValue) -> Expression

Construct a date from a proleptic Gregorian ordinal.

Parameters:

• ordinal

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

Returns:

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

.to_datetime()

date.to_datetime(
    date: DateValue,
    hour: int = 0,
    minute: int = 0,
    second: int = 0,
    millisecond: int = 0,
    tz: str = "UTC",
) -> Expression

Convert a date to a datetime with specified time components.

Parameters:

• date

  (DateValue) - The date to convert.

• hour

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

• minute

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

• second

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

• millisecond

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

• tz

  (str, default: “UTC”) - The timezone string. Default: “UTC”.

Returns:

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

.format()

date.format(date: DateValue, format: StringValue) -> Expression

Format a date as a string.

Parameters:

• date

  (DateValue) - The date to format.

• format

  (StringValue) - The format string.

Returns:

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

Referenced By:

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Use advanced reasoning > Rules-based reasoning
        └──  Work with strings

.add()

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

Add a period to a date.

Parameters:

• date

  (DateValue) - The date to add to.

• period

  (Variable) - The period to add (use days(), weeks(), months(), years()).

Returns:

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

Examples:

Add periods to dates:

>>> datetime.date.add(Order.order_date, datetime.days(7))
>>> datetime.date.add(Project.start_date, datetime.weeks(Contract.duration_weeks))
>>> datetime.date.add(Subscription.start_date, datetime.months(12))

.subtract()

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

Subtract a period from a date.

Parameters:

• date

  (DateValue) - The date to subtract from.

• period

  (Variable) - The period to subtract (use days(), weeks(), months(), years()).

Returns:

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

.range()

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

Generate a range of dates.

Parameters:

• start

  (DateValue | None, default: None) - The start date. If None, computes from end.

• end

  (DateValue | None, default: None) - The end date (inclusive). If None, uses periods.

• periods

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

• freq

  (Frequency, default: “D”) - Frequency: “D” (day), “W” (week), “M” (month), “Y” (year). Default: “D”.

Returns:

• Variable - A Variable representing the date range. Returns Date.

Raises:

• ValueError - If neither start nor end is provided, or if freq is invalid.

Referenced By:

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

.period_days()

date.period_days(start: DateValue, end: DateValue) -> Expression

Compute the number of days between two dates.

Parameters:

• start

  (DateValue) - The start date.

• end

  (DateValue) - The end date.

Returns:

• Expression - An Expression computing the number of days. Returns Integer.

.diff()

date.diff(part: DatePart, start: DateValue, end: DateValue) -> Expression

Calculate the difference between two dates in the specified date part units.

Parameters:

• part

  (DatePart) - The unit to measure the difference in: “year”, “quarter”, “month”, “week”, or “day”.

• start

  (DateValue) - The start date.

• end

  (DateValue) - The end date.

Returns:

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

Examples:

Calculate date differences:

>>> datetime.date.diff("day", Order.start_date, Order.end_date)
>>> datetime.date.diff("month", Employee.hire_date, Employee.termination_date)
>>> datetime.date.diff("week", Project.start, Project.finish)

.fromisoformat()

date.fromisoformat(date_string: StringValue) -> Expression

Parse a date from ISO format string (yyyy-mm-dd).

Parameters:

• date_string

  (StringValue) - The ISO format date string.

Returns:

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

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

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