From cec14ac57a1ad682eb565b5ba1be54067c379193 Mon Sep 17 00:00:00 2001
From: Benjamin Trent <4357155+benwtrent@users.noreply.github.com>
Date: Fri, 23 Feb 2024 10:29:08 -0500
Subject: [PATCH] Add note about optional times and epochs

---
 docs/reference/mapping/params/format.asciidoc | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/reference/mapping/params/format.asciidoc b/docs/reference/mapping/params/format.asciidoc
index dff7bb4a11ee4..5babb4def2320 100644
--- a/docs/reference/mapping/params/format.asciidoc
+++ b/docs/reference/mapping/params/format.asciidoc
@@ -70,6 +70,11 @@ The following tables lists all the defaults ISO formats supported:
     (separated by `T`), is optional.
     Examples: `yyyy-MM-dd'T'HH:mm:ss.SSSZ` or  `yyyy-MM-dd`.
 
+    NOTE: When using `date_optional_time`, the parsing is lenient and will attempt to parse
+    numbers as a year (e.g. `292278994` will be parsed as a year). This can lead to unexpected results
+    when paired with a numeric focused format like `epoch_second` and `epoch_millis`.
+    It is recommended you use `strict_date_optional_time` when pairing with a numeric focused format.
+
 [[strict-date-time-nanos]]`strict_date_optional_time_nanos`::
 
     A generic ISO datetime parser, where the date must include the year at a minimum, and the time