Date Format Patterns

Values of fields of type DATE can be formatted in various ways. By default, FACT-Finder recognizes two date formats: ISO-8601 dates and UNIX timestamps (in milliseconds). 

If the provided values of a date field are formatted in a way different from ISO-8601 and a timestamp in milliseconds, since version NG 3.0 a pattern describing this format can be defined on the corresponding field. FACT-Finder will then recognize the customized format in addition to the two default date formats. 

In order to work correctly, the configured pattern must conform with the specifications of date format patterns provided in the following paragraphs. 

Please note that the configured pattern is exclusively used for parsing the date values during data imports. Dates, which are returned by the REST API or displayed in the cockpit, are always formatted in ISO-8601 format.

Dates

The date format pattern is based on a sequence of encoding symbols. In this section, we specify how to define a pattern for date formats containing year, month and day.

We strongly advise you to include a time zone format in every date format and a time zone in every date value. More information about this topic can be found in the section “Time zone” below.

Please be aware that provided values that contain a date, but no time, will always contain the time 0:00 am implicitly. Thus, we advise you to always include a time in the provided value, too. 

Common examples for dates:

Time

The values of date fields in FACT-Finder always represent a certain point in time. If they do not contain any information regarding the time, they will be considered to represent the start of the day.  

In order to provide time information, either the 24-hour format or the 12-hour format can be used. Missing information on the value of hour, minute, and/or second will be parsed as 0. 

24-hour format: 

Common examples for the 24-hour-format:

12-hour format:

Common examples for the 12-hour format:

Time zone

FACT-Finder will convert every provided date value into the time zone of the server it is hosted on. 
The time zone of the server can be found in every date returned or displayed by FACT-Finder, since those are always formatted according to ISO-8601. 

If a date value does not contain information regarding the time zone, FACT-Finder will interpret the date with the time zone of the server that runs FACT-Finder. That's why we suggest to always provide the time zone. Without a specified time zone, results will be less predictable.

The time zone information can be specified in the pattern by using the following symbols:

Examples:

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. FACT-Finder will always reference that exact same point in time. However, please be aware that the day in the resulting ISO-8601 date may differ from the provided value, due to time differences between the hosting location and the given time zone (see example #3 below).

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: