Date Format Patterns

Summary

Fields of type DATE support multiple input formats. By default, two formats are recognized:

1. ISO-8601 (e.g., 2025-06-30T15:00:00Z)

2. UNIX Timestamps in milliseconds (e.g., 1730342400000)

Starting with version 3.0, you can define a custom date pattern for a DATE field if your data uses a format other than the defaults above. This allows the FactFinder system to parse dates correctly during data import.

The custom date pattern must conform to the standard Java date format patterns (as described in the following sections).

Important:
Custom patterns are only used for parsing imported data. Regardless of the input format, all dates are returned by the REST API and displayed in the Cockpit in ISO-8601 format.

Dates

Date format patterns are defined using a sequence of encoding symbols, each representing components like year, month, and day. In this section, we explain how to construct patterns that include these elements.

Best Practice: Always include a time zone format in your date pattern and ensure that every date value includes a time zone. This helps avoid ambiguity and ensures consistent parsing across systems.
More details are available in the section titled “Time Zone.”

Note: If a provided date value includes only the date (year, month, day) and omits the time, the system will automatically assume a time of 00:00 (midnight). To avoid unintended behavior, we recommend always including a time component in your date values.

Common examples for dates:

Time

The values of DATE fields always represent a specific point in time. If a value does not include time information, it is interpreted as referring to the start of the day (i.e., 00:00:00). To explicitly provide time information, you can use either the 24-hour format (e.g., 14:30) or the 12-hour format with an AM/PM marker (e.g., 02:30 PM).

Note: If any part of the time—such as hour, minute, or second—is omitted, it will default to 0.
For example, 2025-06-30 will be interpreted as 2025-06-30T00:00:00.

Common examples for the 24-hour format:

Common examples for the 12-hour format:

Time zone

FactFinder converts every provided date value to the time zone of the server it is hosted on. This server time zone is reflected in all date values returned or displayed by FactFinder, as they are formatted using the ISO-8601 standard.

If a date value does not include time zone information, FactFinder will interpret it using the server’s default time zone.

Recommendation: Always include a time zone in your date values to ensure consistent and predictable results. Omitting the time zone can lead to unexpected behavior, especially across different deployments or environments.

You can specify time zone information in a date pattern using the following symbols:

Examples:

If dates do not contain information about their time zone, they are interpreted in the time zone of the hosting server (see example #1 below).

As mentioned above, dates without a specified time are interpreted to reference the start of the day. By specifying the time zone, the provided value will reference the start of the given day in that time zone. FactFinder-NG When a time zone is explicitly specified, the value is understood to represent the start of the given day in that specific time zone. FactFinder-NGwill consistently treat this as a fixed point in time, regardless of where it is processed.

Free text

All letters A to Z and a to z are reserved pattern symbols. Any non-letter character, other than '[', ']', '{', '}', '#' and the single quote, will be parsed as is.

You can mask letters by surrounding them with single quotes (') if you want to use them in free text. Use a single quote to mask a single quote (''). 

Examples: