Summary
Fields of type DATE
support multiple input formats. By default, two formats are recognized:
ISO-8601 (e.g.,
2025-06-30T15:00:00Z
)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.
Unit | Symbol | Valid Values |
---|---|---|
year | yy | last 2 digits of a year within the range 2000 to 2099 |
yyyy | 4 digits of a year | |
month | M | 1 to 12 as well as 01 to 12 |
month (name, in English) | MMM | 3-letter code, e.g., Jan, Feb, ... |
| MMMM | full name |
day (of month) | d | 1 to 31 as well as 01 to 31 |
day (of week, in English) | eee | Mon to Sun |
| eeee | Monday to Sunday |
Common examples for dates:
Full pattern | Example date value |
---|---|
yyyy M d z | 1999 3 22 UTC |
yyyy MMMM d z | 2022 March 22 CET |
d MMM yy z | 1 Jan 22 CET |
eee d M yyyy z | Tue 22 3 2006 UTC |
eeee d MMMM yyyy z | Tuesday 22 March 2006 CET |
d.M.yyyy z | 22.8.1999 CEST |
yyyy.M.d z | 1999.03.22 UTC |
yyyy. M. d. z | 2033. 3. 22. CET |
d-M-yyyy z | 22-03-2010 UTC |
M-d-yy z | 3-22-10 CET |
yyyy-M-d z | 1999-03-22 UTC |
M/d/yy z | 3/22/10 CET |
d. MMMM yyyy z | 22. March 2001 UTC |
MMMM d, yyyy z | March 22, 2041 CET |
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 as2025-06-30T00:00:00
.
24-hour format
Unit | Symbol | Valid Values |
---|---|---|
hour of day | H | 0 to 23 as well as 00 to 23 |
minute | m | 0 to 59 as well as 00 to 59 |
second | s | 0 to 59 as well as 00 to 59 |
second | ss | 00 to 59 |
second incl. milliseconds | ss.SSS | 00.000 to 59.999 |
Common examples for the 24-hour format:
Full pattern | Example date value |
---|---|
d.M.yyyy H:m z | 22.03.2020 13:37 CET |
d.M.yyyy H:m:s z | 22.03.2020 13:37:05 CET |
d.M.yyyy H.m z | 22.03.2020 13.37 UTC |
d.M.yyyy H:m:ss.SSS z | 22.11.2022 15:57:06.539 CET |
12-hour format
Unit | Symbol | Valid Values |
---|---|---|
hour of AM/PM | K | 0-11 (with 0:00 AM equal to 0:00 and 0:00 PM equal to 12:00) |
minute | m | 0 to 59 as well as 00 to 59 |
second | s | 0 to 59 as well as 00 to 59 |
second | ss | 00 to 59 |
second incl. milliseconds | ss.SSS | 00.000 to 59.999 |
am/pm | a | AM or PM |
Common examples for the 12-hour format:
Full pattern | AM example | PM example |
---|---|---|
d.M.yyyy K:m a z | 22.03.1999 8:15 AM UTC | 22.03.1999 08:15 PM UTC |
d.M.yyyy K:m:s a z | 22.03.1999 08:15:00 AM UTC | 22.03.1999 10:22:13 PM UTC |
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:
Unit | Symbol | Valid Values (examples) |
---|---|---|
time zone ID | VV | Europe/Berlin; Europe/Lisbon |
time zone name | z | PST; UTC; CET |
| zzzz | Pacific Standard Time; Universal Coordinated Time |
time zone offset | X | Z; +00; -08 |
| XXXX | Z; -0830; +083015 |
| XXXXX | Z; 08:30; +08:30:15 |
time zone offset (in English) | O | GMT; GMT+8; GMT-08:00 |
Examples:
Full pattern | Example Value | Resulting ISO-8601 (assuming FactFinder is hosted in Germany) |
---|---|---|
d.M.yyyy H:mXXXX | 30.08.2022 08:15+0200 | 2022-08-30T08:15:00+02:00 |
d.M.yyyy H:m O | 22.02.2022 08:15 GMT+2 | 2022-02-22T07:15:00+01:00 |
d.M.yyyy H:m z | 22.02.2022 05:06 PDT | 2022-02-22T14:06:00+01:00 |
d.M.yyyy H:m z | 22.02.2022 05:06 CET | 2022-02-22T05:06:00+01:00 |
d.M.yyyy H:m zzzz | 22.02.2022 05:06 Universal Coordinated Time | 2022-02-22T06:06:00+01:00 |
Special case: time not provided but time zone provided (not suggested!)
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.
Example value | Start of the day in: | Resulting ISO-8601 (assuming FactFinder is hosted in Germany) |
---|---|---|
30.08.2022 | hosting location i.e. Berlin | 2022-08-30T00:00:00+02:00 |
30.08.2022+0100 | London | 2022-08-30T01:00:00+02:00 |
30.08.2022+0300 | Moscow | 2022-08-29T23:00:00+02:00 |
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:
Full pattern | example date value |
---|---|
d. MMM ''yy z | 22. Jan '99 UTC |
'Export date:' yyyy M d z | Export date: 1999 03 22 UTC |
d'x'M'x'yyyy’x’z | 22x3x1999xUTC |
d.M.yyyy H'h'm z | 22.03.1999 13h37 CET |
d.M.yyyy 'at' H:m z | 22.03.1999 at 13:37 CET |
d.M.yyyy H 'o''clock' z | 22.03.1999 5 o'clock UTC |