Skip to main content
Version: Python


Durations are a special type of string used to represent a period of wall clock time (i.e. hours, minutes, seconds, nanoseconds).


[-]PTnHnMnS or [-]PT00:00:00.000000

  • [-] - An optional sign to indicate that the period is negative. Omitting this makes the period positive.
  • PT - The prefix indicating this is a duration string.
  • n - A numeric value
  • H - Hours
  • M - Minutes
  • S - Seconds

Each #[H|M|S] value translates to a part of the duration. A valid duration string can contain nearly any combination of these values. For example, PT1M1S (1 minute and 1 second), PT2H3M (2 hours and 3 minutes), and -PT24H30M2.4S (negative 24 hours, 30 minutes, and 2.4 seconds) are all valid period strings. Alternatively, the PT00:00:00.000000 format can be used.


The following example uses to_j_duration to convert duration strings to duration objects.

from deephaven.time import to_j_duration

five_hours = to_j_duration("PT5H")
one_minute_fifteen_seconds = to_j_duration("PT00:01:15")
negative_one_hour = to_j_duration("PT-1H")


The following example uses pandas to add durations to a date-time object before converting it to a Java Instant via to_j_instant.

from pandas import to_datetime, to_timedelta
from deephaven.time import to_j_duration, to_j_instant

date_time = to_datetime("2020-01-01T00:00:00Z", format = "ISO8601")
pos_duration = to_timedelta("1h")
neg_duration = to_timedelta("-1m1s")

print(to_j_instant(date_time + pos_duration))
print(to_j_instant(date_time + neg_duration))