Deephaven's modernized time library -- Part 2

Deephaven Core v0.28 introduces a second set of major changes to modernize date-time handling in Python. A rework of deephaven.time makes working with dates and times more Pythonic. You can now seamlessly convert between Python, NumPy, and Pandas date-times and Java date-times used in Deephaven queries.

In older Deephaven versions, users were often confused about when to use deephaven.time methods vs built-in query language methods. The problem was amplified by methods having very similar names. The confusion resulted in unnecessarily slow queries or ones that break altogether. The new deephaven.time changes should make it more apparent when the often slower deephaven.time is being used in place of the often faster built-in query language methods.

The new time library clarifies method names and makes it easier to choose between `deephaven.time` methods and built-in query language methods, resulting in more efficient queries.

Supported types include:

• Nanoseconds since the Epoch (int)
• str
• datetime.date
• datetime.time
• datetime.datetime
• datetime.timedelta
• datetime.tzinfo
• numpy.datetime64
• numpy.timedelta64
• pandas.Timestamp
• pandas.Timedelta
• java.time.LocalDate / deephaven.dtypes.LocalDate
• java.time.LocalTime / deephaven.dtypes.LocalTime
• java.time.Instant / deephaven.dtypes.Instant
• java.time.ZonedDateTime / deephaven.dtypes.ZonedDateTime
• java.time.Duration / deephaven.dtypes.Duration
• java.time.Period / deephaven.dtypes.Period
• java.time.ZoneId /deephaven.dtypes.TimeZone

Example

Let's look at a quick example to illustrate the changes. Here, five different Python date-time types are used to create a single timestamp column in a Deephaven table. Then, Python datetime arithmetic and to_j_instant are combined to create a java.time.Instant for use in a query string.

import datetime
import pandas as pd
import numpy as np

from deephaven import new_table
from deephaven.column import datetime_col, int_col
from deephaven.time import to_j_instant

first_time = 1694543451
second_time = "2021-07-04T08:00:00 ET"
third_time = datetime.datetime(2021, 9, 6, 12, 30)
fourth_time = pd.Timestamp(year=2021, month=12, day=25, hour=21, minute=15)
fifth_time = np.datetime64("2021-12-25T21:15:00")

# Create a table with a timestamp column
t1 = new_table([
    datetime_col("Timestamp", [first_time, second_time, third_time, fourth_time, fifth_time]),
    int_col("Value", [1, 2, 3, 4, 5])
])

# Create a Java Instant that can be used efficiently in the Deephaven query strings
filter_time = to_j_instant( third_time + datetime.timedelta(days=90) )
t2 = t1.where("Timestamp > filter_time")

t1

t2

Updating your queries

When porting older scripts to Deephaven v0.28, see our Pydoc to reference the new Python time API. Infrequently used methods and methods specific to Java types have been removed. Equivalent date-time calculations can be performed using Python date-time libraries.

If you need help porting your code, please get in touch with Deephaven on Slack.

note

These changes build on our previous rewrite of the Python library, detailed in our previous blog post. A third major update to Deephaven's time library is coming soon, and will include a rework of Deephaven's calendars.