DateTime Resolver ≥0.1.0

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

For version ≥0.1.0 and <0.3.0, The input string is parsed according to the configured format (using C++ strftime-style format specifiers). Only one granularity may be used, and depending on the chosen granularity, a fractional value is extracted from the parsed time and mapped onto a 2-dimensional embedding.

Note

The timestamp granularity is valid on ≥0.3.0 only and if it is specified, the format parameter is ignored. weekday is only guaranteed to work on ≥0.3.0, but may work on previous versions as it still matches a strftime format.

For versions ≥0.3.0, the legacy behaviour is preserved, but the granularity can also be an array of strings. In this configuration the format parameter is no longer used, and the DateTime Resolver is a compound resolver, therefore the number of dimensions used in the embedding can be different based on resolver settings. I.e. dimensions that correspond to a certain granularity are only set if that granularity is provided in the granularity array. When training data, all specified granularities in the granularity array will be used to generate a multidimensional embedding. When querying, the input string used in the query will determine which granularity is queried. How the input string relates to each granularity is specified in the Accepted Formats section below.

For cyclic granularities (hour, day, weekday, 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 and timestamp granularities, 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 scaled by an optional multiplier.

Settings

Setting	Type	Default	Description
granularity	(≥0.1.0) string / (≥0.3.0)string[]	-	≥0.1.0 Contains a single granularity. ≥0.3.0 Can contain subset of granularities: "hour", "day", "weekday" (≥0.3.0), "month", "year", or "timestamp" (≥0.3.0).
format	string	""	Format string used to parse the input (see format specifiers). Only used for legacy case of datetime resolver.
minYear	integer	1970	Minimum year (inclusive). Only used when granularity includes "year" or "timestamp".
maxYear	integer	2030	Maximum year (inclusive). Only used when granularity includes "year" or "timestamp".

Embedding Size

The datetime resolver produces up to 10 dimensions (2 per granularity, note that timestamp and year are different representations of the same thing, so both only count as 1 granularity). Depending on granularity matched, some dimensions may be ignored when querying, but during training all specified granularities are used.

Granularity Modes

Granularity	Cyclic	Range	Description
hour	Yes	2π	Maps the hour of day to a circular embedding. Minutes and seconds add fractional precision.
weekday (≥0.3.0)	Yes	2π	Maps the day of the week to a circular embedding. Hours, minutes, and seconds add precision.
day	Yes	2π	Maps the day of the 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.
timestamp (≥0.3.0)	No	1.5π	Maps the timestamp linearly within [minYear, maxYear]. Directly uses the underlying Unix timestamp.

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 array must contain at least 1 of the following: "hour", "weekday", "day", "month", "year", "timestamp".
• When granularity includes "year" or "timestamp", minYear must be ≤ maxYear, and the input year must fall within [minYear, maxYear].
• With version ≥0.1.0 and <0.3.0, the format is specified by the format argument in the resolver settings. In version ≥0.3.0 The input string must match one of several pre-defined formats listed below, except for the case where only granularity is specified - and it's not "timestamp" - and format is provided, then format is used instead of predefined formats: this is only intended as a measure to maintain backwards-compatibility and should not be used going forward, as the strftime parsing used in custom formats is not reliable.

Accepted Formats (≥0.3.0)

When querying, you can specify any of the following predefined formats, and if the format is enabled within the resolver with the granularity array, it will match and query on the corresponding granularity.

Note

Numeric date inputs must be zero-padded to fixed length. E.g. for a day format dd, it must always be written as two digits, so the first day of the month would be written as 01, not 1. This does not apply to strings. Additionally, timestamp does not have a fixed length. Refer to the Length column below for details.

Format	Example	Matching Granularity	Length
YYYY/mm/dd hh:mm:ss	2026/04/20 12:05:00	year	{4}/{2}/{2} {2}:{2}:{2}
YYYY	2026	year	{4}
YYYY/mm	2026/04	year	{4}/{2}
YYYY Month	2026 Apr	year	{4}
Month	April	month	{string}
Month	Apr	month	{string}
mm/dd	04/20	month	{2}/{2}
Month dd	Apr 20	month	{string}
dd	20	day	{2}
dd hh:mm:ss	20 12:05:00	day	{2} {2}:{2}:{2}
dd hh:mm	20 12:05	day	{2} {2}:{2}
Weekday	Monday	weekday	{string}
Weekday	Mon	weekday	{string}
Weekday hh:mm:ss	Mon 12:05:00	weekday	{string} {2}:{2}:{2}
Weekday hh:mm	Mon 12:05	weekday	{string} {2}:{2}
hh:mm:ss	12:05:00	hour	{2}:{2}:{2}
hh:mm	12:05	hour	{2}:{2}
Timestamp	1776686700	timestamp	{>1}

Example

{
  "name": "created_at",
  "type": "datetime",
  "path": "$.created_at",
  "settings": {
    "granularity": ["day", "hour"]
  },
  "multiplier": 1.0
}

Input:

{ "created_at": "2020/05/20 13:30:09" }

When used in query (focussing on hour granularity):

{ "created_at": "13:30" }