# 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.

| 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 as `2025-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 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    | <p>22.02.2022 05:06 CET<br></p>             | 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 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    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fact-finder.com/docs/basic-settings/fields/date-format-patterns.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.