DateTime Resolver

The datetime resolver maps a date/time string to a radial embedding. It supports several granularity levels, making it suitable for fields such as timestamps, publication dates, or event times.

How It Works

The input string is parsed according to the configured format (using C++ strftime-style format specifiers). Depending on the chosen granularity, a fractional value is extracted from the parsed time and mapped onto a radial embedding.

For cyclic granularities (hour, day, month), the full 2π range is used so that, for example, the end of a month wraps around to the start. For the non-cyclic year granularity, a 1.5π range is used (the same approach as the number resolver) to ensure years at opposite ends of the range remain distinct.

The output is always a two-dimensional vector of (cos θ, sin θ) coordinates, scaled by an optional multiplier.

Settings

Setting	Type	Default	Description
granularity	string	"day"	Time granularity: "hour", "day", "month", or "year".
format	string	"%Y/%m/%d %H:%M:%S"	Format string used to parse the input (see format specifiers).
multiplier	number	1.0	Scaling factor applied to the embedding. Increase to give this aspect more weight.
minYear	integer	1970	Minimum year (inclusive). Only used when granularity is "year".
maxYear	integer	2030	Maximum year (inclusive). Only used when granularity is "year".

Embedding Size

The datetime resolver always produces 2 dimensions.

Granularity Modes

Granularity	Cyclic	Range	Description
hour	Yes	2π	Maps the hour of day to a circular embedding. Minutes and seconds add fractional precision.
day	Yes	2π	Maps the day of month to a circular embedding. Hours, minutes, and seconds add precision.
month	Yes	2π	Maps the month of year to a circular embedding. Days and sub-day components add precision.
year	No	1.5π	Maps the year linearly within [minYear, maxYear]. Months and sub-month components add precision.

Note

With the day granularity, the resolver does not account for varying month lengths or leap years as it uses a fixed 31-day range for the embedding. This means that the distance between the last day of one month and the first day of the next month varies between longer and shorter months.

Validation

• granularity must be one of "hour", "day", "month", or "year".
• When granularity is "year", minYear must be ≤ maxYear, and the input year must fall within [minYear, maxYear].
• The input string must match the configured format exactly.

Example

{
  "name": "created_at",
  "type": "datetime",
  "path": "$.created_at",
  "settings": {
    "granularity": "day",
    "format": "%Y/%m/%d %H:%M:%S",
    "multiplier": 1.0
  }
}

With granularity set to "year":

{
  "name": "published_year",
  "type": "datetime",
  "path": "$.published",
  "settings": {
    "granularity": "year",
    "format": "%Y/%m/%d",
    "minYear": 2000,
    "maxYear": 2030,
    "multiplier": 1.0
  }
}