Skip to content

relationalai.std.dates.nanoseconds()

nanoseconds(n: int|Producer) -> Expression

Creates a period of n nanoseconds. Negative values are supported. If n is a Producer object, then nanoseconds() also acts as a filter and removes non-integer values from the producer. Like microseconds(), nanoseconds() can only be added or subtracted from datetime values. Must be called in a rule or query context.

Parameters

Name	Type	Description
`n`	`Producer` or Python `int`	The number of nanoseconds.

Returns

An Expression object.

Example

Use nanoseconds() to create a period of n nanoseconds. You can add and subtract time periods from datetime values using the + and - operators:

import relationalai as rai
from relationalai.std import alias, dates


# =====
# SETUP
# =====

model = rai.Model("MyModel")
Event = model.Type("Event")

with model.rule():
    Event.add(id=1).set(start=dates.datetime(2021, 1, 1, 9, 30), duration_nanoseconds=500)
    Event.add(id=2).set(start=dates.datetime(2021, 2, 1, 9, 30), duration_nanoseconds=-250)
    Event.add(id=3).set(start=dates.date(2021, 3, 1), duration_nanoseconds=1000)
    Event.add(id=4).set(start=dates.date(2021, 4, 1), duration_nanoseconds="invalid")


# =======
# EXAMPLE
# =======

with model.rule():
    event = Event()
    # nanoseconds() filters out any events with invalid start or duration_nanoseconds values,
    # so the following only sets the end property for Events 1 and 2. Event 3 is
    # filtered out because its start property is a date value, while Event 4 has
    # both an invalid start and duration_nanoseconds value.
    event.set(end=event.start + dates.nanoseconds(event.duration_nanoseconds))
    # Since Event 3 and 4 are filtered out above, the following only sets the
    # has_valid_start_and_duration property for Events 1 and 2.
    event.set(has_valid_start_and_duration=True)

with model.query() as select:
    event = Event()
    response = select(event.id, event.end, event.has_valid_start_and_duration)

# NOTE: pandas displays datetimes with second precision.
print(response.results)
#    id                 end has_valid_start_and_duration
# 0   1 2021-01-01 09:30:00                         True
# 1   2 2021-02-01 09:30:00                         True
# 2   3                 NaT                          NaN
# 3   4                 NaT                          NaN

You can add nanoseconds() to date values if you first convert them to datetime values using the datetime.fromdate() constructor:

# Alternative version of the rule in the preceding example that converts any date
# values produced by event.start to datetime values before adding the duration.
with model.rule():
    event = Event()
    duration_nanoseconds = dates.nanoseconds(event.duration_nanoseconds)
    with model.match():
        # If event.start is a date, convert it to a datetime before adding the duration.
        with model.case():
            dates.Date(event.start)
            date_as_time = dates.datetime.fromdate(event.start)
            event.set(end=date_as_time + duration_nanoseconds)
        # Otherwise, add the duration without conversion.
        with model.case():
            event.set(end=event.start + duration_nanoseconds)

with model.query() as select:
    event = Event()
    response = select(event.id, event.end)

# Event 4 is still filtered out, but Event 3 now has an end property.
# NOTE: pandas displays datetimes with second precision.
print(response.results)
#    id                 end
# 0   1 2021-01-01 09:30:00
# 1   2 2021-02-01 09:30:00
# 2   3 2021-03-01 00:00:00
# 3   4                 NaT

Note that nanoseconds() does not produce an integer value. In particular, you cannot do arithmetic with nanoseconds() and numeric values:

with model.query() as select:
    result = dates.nanoseconds(500) / 1000
    response = select(result)

# Returns an empty result set because `nanoseconds(500) / 1000` is not a valid expression.
print(response.results)
# Empty DataFrame
# Columns: []
# Index: []

See Also