Date Format Patterns

Prev Next

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.

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 

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) 

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 as 2025-06-30T00:00:00.


24-hour format

Unit 

Symbol 

Valid Values 

hour of day 

0 to 23 as well as 00 to 23 

minute 

0 to 59 as well as 00 to 59 

second 

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 

0-11 (with 0:00 AM equal to 0:00 and 0:00 PM equal to 12:00)

minute 

0 to 59 as well as 00 to 59 

second 

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 

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 

PST; UTC; CET 

 

zzzz 

Pacific Standard Time; Universal Coordinated Time 

time zone offset 

Z; +00; -08 

 

XXXX 

Z; -0830; +083015 

 

XXXXX 

Z; 08:30; +08:30:15 

time zone offset (in English) 

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