Time Units: Period, Duration, and Interval

The C3 Agentic AI Platform provides three distinct types for representing time: Period, Duration, and Interval. Each serves a different purpose and has different string formats.

Copy link to this section

Period - Logical Time Units

A Period represents a logical time unit with a count and unit (for example, "30 days"). Periods are "logical" because they can represent calendar units that vary in actual length. For example, a Period can be "3 months", but a Duration cannot represent months directly, it would need to be an exact number of days like "90d" or "92d" depending on which months are included.

Periods are stored in logical form and make no assumptions. They use canonical assumptions (month = 30 days, year = 365 days) only when converting to physical units like Duration. Periods are calendar-aware. For units smaller than a day (hours, minutes, seconds, etc.), physical and logical units are the same, so Period and Duration behave equivalently.

Copy link to this section

String Format

{count}{unit} or {count}{unit}@{offset}

Examples:

• "30d" - 30 days
• "1mo" - 1 month (canonical 30 days)
• "1w@6" - 1 week starting Saturday (offset 6)
• "1q@2" - 1 quarter starting in February
• "1y" - 1 year (canonical 365 days)

Supported Units:

• y (year), q (quarter), mo (month), w (week)
• d (day), h (hour), m (minute), s (second)
• ms (millisecond), µs (microsecond), ns (nanosecond)

Key Features:

• Single unit per Period (not "7d 8h")
• Uses the TemporalUnit enum (similar to Interval, but includes values not supported by NormTimeseries)
• Supports offsets for calendar alignment (@offset)
• Canonical conversions: month = 30 days, year = 365 days
• Can convert to Duration (with canonical assumptions) or Interval (if matches predefined values)

Use Cases: Timeseries intervals, calendar-based periods, logical time units with custom offsets

Copy link to this section

Period Offset

The offset field allows you to shift the start of a Period to align with custom calendar boundaries.

Format: {period}@{offset}

Supported Units & Offset Ranges:

Examples:

• "w@1" - Week starting Monday (default)
• "w@7" - Week starting Sunday
• "1mo@15" - Month starting on the 15th day
• "Q@2" - Quarters starting in February (Feb, May, Aug, Nov)
• "Y@9" - Fiscal year starting in September

The alignedTimePoint(dt) method finds the most recent period boundary based on the offset.

Copy link to this section

Duration - Exact Elapsed Time

A Duration represents exact elapsed time stored in microseconds. It is a fixed number of microseconds long, regardless of calendar context. Duration is unable to represent calendar units that have variable lengths, such as months. Instead, it requires the use of precise day counts. For example, rather than specifying "3 months," you must provide the exact number of days, such as "90d" or "92d".

Copy link to this section

String Format

Multiple unit pairs concatenated: {count}{unit}{count}{unit}...

Examples:

• "5h3m45s350ms" - 5 hours, 3 minutes, 45 seconds, 350 milliseconds
• "1d1h1m1s1ms" - 1 day, 1 hour, 1 minute, 1 second, 1 millisecond
• "75m" - 75 minutes
• "1.25h" - 1.25 hours (fractional supported)
• "1h-1m" - 59 minutes (negative components allowed)

Supported Units (only up to days):

• d (day), h (hour), m (minute), s (second)
• ms (millisecond), µs (microsecond)

Key Features:

• Multiple units allowed (unlike Period)
• Supports fractional values ("1.25h")
• Supports negative components ("1h-1m" = 59 minutes)
• Stored as microseconds internally
• No calendar context - pure elapsed time

Use Cases: Timeouts, sleep durations, elapsed time calculations, performance measurements

Copy link to this section

Interval - Predefined Timeseries Intervals

An Interval is an enum of predefined intervals for timeseries operations. These map to specific Period values.

Copy link to this section

Enum Values

SECOND, MINUTE, FIVE_MINUTE, TEN_MINUTE, QUARTER_HOUR, HALF_HOUR, HOUR, DAY, MONTH, YEAR

Examples:

• Interval.QUARTER_HOUR → Period "15m"
• Interval.HALF_HOUR → Period "30m"
• Interval.DAY → Period "1d"

Key Features:

• Predefined set of common intervals
• Can convert to Period via Interval.toPeriod()
• Used for timeseries interval/aggregation
• Provides alignment methods (alignDate, nextTimePoint, prevTimePoint)

Use Cases: Timeseries interval specification, data aggregation intervals, time alignment operations

Copy link to this section

Comparison Table

Copy link to this section

Conversion Examples

// Period → Duration (canonical)
Period.fromString("1mo").toDuration()  // → Duration("30d")

// Period → Interval
Period.fromString("15m").toInterval()  // → Interval.QUARTER_HOUR

// Interval → Period
Interval.toPeriod(Interval.QUARTER_HOUR)  // → Period("15m")

// Duration → Interval (closest match)
Duration.fromString("1h").toClosestInterval()  // → Interval.HOUR

Copy link to this section

When to Use Which?

• Use Period for: calendar-based periods (especially months/years), timeseries intervals, logical time units with offsets. Use when you need to represent "3 months" as a concept rather than an exact number of days.
• Use Duration for: exact elapsed time, timeouts, sleep, performance measurements. Use when you need a fixed number of microseconds (e.g., "90d" for exactly 90 days, not "3 months" which could be 90-92 days).
• Use Interval for: predefined timeseries intervals, when you need alignment operations. Since it's an enum, it's harder to confuse with Period or Duration.

Copy link to this section

Related Content

• Period - Period type reference
• Duration - Duration type reference
• Interval - Interval type reference
• TemporalUnit - Temporal unit enum reference
• Time Series Guide