Time and Calendars

This section covers working with time and calendars in Deephaven queries. Since Deephaven specializes in real-time operations, understanding how to work with time is crucial to building effective analyses.

Critical concepts covered in this crash course include:

Time data types

Deephaven tables natively support all data types found in the java.time package.

Commonly used types include:

  • Instant: A specific point in time
  • ZonedDateTime: A specific point in time with time zone information
  • LocalDate: A date without time zone information
  • Duration: A length of time; e.g. 5 minutes, 1 hour, etc.
  • Period: A date-based amount of time (like "2 months")

Time constants

Deephaven offers a set of built-in constants for common time periods. All of the following values are expressed in nanoseconds:

Create temporal data

You can create temporal data with query string methods. For instance, you can construct columns with a single timestamp, sequences of timestamps, and more:

Time arithmetic and filtering

Time arithmetic in tables should always be done with built-in methods. See DateTimeUtils for the available constants and methods.

Filtering temporal data isn't much different from filtering numeric data:

Time zones

Time zones are a critical part of temporal data. For example, if it's 6 PM in Los Angeles, it's 3 AM the next day in Shanghai. There are many methods that require time zone information because the answer is dependent on the time zone.

All of the previous operations use Instant values, which contain no time zone information - hence the need to pass time zones like 'PT' and 'Asia/Shanghai'. Instead, you can bake the time zone information into the data by using ZonedDateTime:

Business calendars

Business calendars help you work with trading days, business hours, and holidays. Deephaven comes with built-in calendars for major exchanges.

Built-in calendars

Deephaven comes with a few built-in calendars.

Note

The built-in calendars are examples. For any production system, a custom or other pre-defined calendar should be used.

Filter by business days and hours

A common use of calendars is to filter data based on whether or not it falls within business hours or on business days.

Common time operations

Aggregations over windows of time are essential for time-series analysis.

Daily summaries

Combine time operations with aggregations for powerful analysis. For example, the following query calculates the daily sum of trades for each ticker:

Aggregations over time buckets

Data is commonly placed into temporal buckets, allowing for analysis of trends over specific intervals. The following query places each trade into a 15-minute bucket, then calculates the average trade price and size for each bucket:

Combine calendar and time methods

Here's a practical example that combines multiple time concepts:

This example demonstrates filtering by business hours, extracting time components, and performing time-based aggregations - all common patterns in financial data analysis.

Next steps

Time handling is crucial for real-time data processing. The concepts covered here form the foundation for more advanced time-series analysis, including: