Add epoch_micros date format (#19245)

mishail · web-flow · commit 34854320d936 · 2025-09-11T19:45:19.000-05:00
Fixes #14669 Signed-off-by: Mikhail Stepura <mstepura@apple.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,6 +18,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Add a dynamic cluster setting to control the enablement of the merged segment warmer ([#18929](https://github.com/opensearch-project/OpenSearch/pull/18929))
 - Publish transport-grpc-spi exposing QueryBuilderProtoConverter and QueryBuilderProtoConverterRegistry ([#18949](https://github.com/opensearch-project/OpenSearch/pull/18949))
 - Support system generated search pipeline. ([#19128](https://github.com/opensearch-project/OpenSearch/pull/19128))
+- Add `epoch_micros` date format ([#14669](https://github.com/opensearch-project/OpenSearch/issues/14669))
 
 ### Changed
 - Add CompletionStage variants to methods in the Client Interface and default to ActionListener impl ([#18998](https://github.com/opensearch-project/OpenSearch/pull/18998))
diff --git a/server/src/main/java/org/opensearch/common/time/DateFormatters.java b/server/src/main/java/org/opensearch/common/time/DateFormatters.java
@@ -2119,6 +2119,8 @@ static DateFormatter forPattern(String input) {
         } else if (FormatNames.EPOCH_MILLIS.matches(input)) {
             return EpochTime.MILLIS_FORMATTER;
             // strict date formats here, must be at least 4 digits for year and two for months and two for day
+        } else if (FormatNames.EPOCH_MICROS.matches(input)) {
+            return EpochTime.MICROS_FORMATTER;
         } else if (FormatNames.STRICT_BASIC_WEEK_DATE.matches(input)) {
             return STRICT_BASIC_WEEK_DATE;
         } else if (FormatNames.STRICT_BASIC_WEEK_DATE_TIME.matches(input)) {
diff --git a/server/src/main/java/org/opensearch/common/time/EpochTime.java b/server/src/main/java/org/opensearch/common/time/EpochTime.java
@@ -49,12 +49,13 @@
 import java.util.Optional;
 
 /**
- * This class provides {@link DateTimeFormatter}s capable of parsing epoch seconds and milliseconds.
+ * This class provides {@link DateTimeFormatter}s capable of parsing epoch seconds, milliseconds, and microseconds.
  * <p>
  * The seconds formatter is provided by {@link #SECONDS_FORMATTER}.
  * The milliseconds formatter is provided by {@link #MILLIS_FORMATTER}.
+ * The microseconds formatter is provided by {@link #MICROS_FORMATTER}.
  * <p>
- * Both formatters support fractional time, up to nanosecond precision.
+ * All formatters support fractional time, up to nanosecond precision.
  *
  * @opensearch.internal
  */
@@ -116,44 +117,62 @@ public long getFrom(TemporalAccessor temporal) {
         }
     };
 
-    // Millis as absolute values. Negative millis are encoded by having a NEGATIVE SIGN.
-    private static final EpochField MILLIS_ABS = new EpochField(ChronoUnit.MILLIS, ChronoUnit.FOREVER, LONG_POSITIVE_RANGE) {
+    private static class AbsoluteEpochField extends EpochField {
+        private final long unitsPerSecond;
+        private final long nanosPerUnit;
+        private final ChronoField unitField;
+        private final EpochField nanosOfUnitField;
+
+        private AbsoluteEpochField(
+            TemporalUnit baseUnit,
+            long unitsPerSecond,
+            long nanosPerUnit,
+            ChronoField unitField,
+            EpochField nanosOfUnitField
+        ) {
+            super(baseUnit, ChronoUnit.FOREVER, LONG_POSITIVE_RANGE);
+            this.unitsPerSecond = unitsPerSecond;
+            this.nanosPerUnit = nanosPerUnit;
+            this.unitField = unitField;
+            this.nanosOfUnitField = nanosOfUnitField;
+        }
+
         @Override
         public boolean isSupportedBy(TemporalAccessor temporal) {
             return temporal.isSupported(ChronoField.INSTANT_SECONDS)
-                && (temporal.isSupported(ChronoField.NANO_OF_SECOND) || temporal.isSupported(ChronoField.MILLI_OF_SECOND));
+                && (temporal.isSupported(ChronoField.NANO_OF_SECOND) || temporal.isSupported(unitField));
         }
 
         @Override
         public long getFrom(TemporalAccessor temporal) {
             long instantSeconds = temporal.getLong(ChronoField.INSTANT_SECONDS);
-            if (instantSeconds < Long.MIN_VALUE / 1000L || instantSeconds > Long.MAX_VALUE / 1000L) {
+            if (instantSeconds < Long.MIN_VALUE / unitsPerSecond || instantSeconds > Long.MAX_VALUE / unitsPerSecond) {
                 // Multiplying would yield integer overflow
                 return Long.MAX_VALUE;
             }
-            long instantSecondsInMillis = instantSeconds * 1_000;
-            if (instantSecondsInMillis >= 0) {
+            long instantSecondsInUnits = instantSeconds * unitsPerSecond;
+            if (instantSecondsInUnits >= 0) {
                 if (temporal.isSupported(ChronoField.NANO_OF_SECOND)) {
-                    return instantSecondsInMillis + (temporal.getLong(ChronoField.NANO_OF_SECOND) / 1_000_000);
+                    return instantSecondsInUnits + (temporal.getLong(ChronoField.NANO_OF_SECOND) / nanosPerUnit);
                 } else {
-                    return instantSecondsInMillis + temporal.getLong(ChronoField.MILLI_OF_SECOND);
+                    return instantSecondsInUnits + temporal.getLong(unitField);
                 }
             } else { // negative timestamp
                 if (temporal.isSupported(ChronoField.NANO_OF_SECOND)) {
-                    long millis = instantSecondsInMillis;
+                    long units = instantSecondsInUnits;
                     long nanos = temporal.getLong(ChronoField.NANO_OF_SECOND);
-                    if (nanos % 1_000_000 != 0) {
+                    if (nanos % nanosPerUnit != 0) {
                         // Fractional negative timestamp.
-                        // Add 1 ms towards positive infinity because the fraction leads
+                        // Add 1 unit towards positive infinity because the fraction leads
                         // the output's integral part to be an off-by-one when the
-                        // `(nanos / 1_000_000)` is added below.
-                        millis += 1;
+                        // `(nanos / nanosPerUnit)` is added below.
+                        units += 1;
                     }
-                    millis += (nanos / 1_000_000);
-                    return -millis;
+                    units += (nanos / nanosPerUnit);
+                    return -units;
                 } else {
-                    long millisOfSecond = temporal.getLong(ChronoField.MILLI_OF_SECOND);
-                    return -(instantSecondsInMillis + millisOfSecond);
+                    long unitsOfSecond = temporal.getLong(unitField);
+                    return -(instantSecondsInUnits + unitsOfSecond);
                 }
             }
         }
@@ -166,19 +185,19 @@ public TemporalAccessor resolve(
         ) {
             Long sign = Optional.ofNullable(fieldValues.remove(SIGN)).orElse(POSITIVE);
 
-            Long nanosOfMilli = fieldValues.remove(NANOS_OF_MILLI);
-            long secondsAndMillis = fieldValues.remove(this);
+            Long nanosOfUnit = fieldValues.remove(nanosOfUnitField);
+            long secondsAndUnits = fieldValues.remove(this);
 
             long seconds;
             long nanos;
             if (sign == NEGATIVE) {
-                secondsAndMillis = -secondsAndMillis;
-                seconds = secondsAndMillis / 1_000;
-                nanos = secondsAndMillis % 1000 * 1_000_000;
-                // `secondsAndMillis < 0` implies negative timestamp; so `nanos < 0`
-                if (nanosOfMilli != null) {
+                secondsAndUnits = -secondsAndUnits;
+                seconds = secondsAndUnits / unitsPerSecond;
+                nanos = secondsAndUnits % unitsPerSecond * nanosPerUnit;
+                // `secondsAndUnits < 0` implies negative timestamp; so `nanos < 0`
+                if (nanosOfUnit != null) {
                     // aggregate fractional part of the input; subtract b/c `nanos < 0`
-                    nanos -= nanosOfMilli;
+                    nanos -= nanosOfUnit;
                 }
                 if (nanos != 0) {
                     // nanos must be positive. B/c the timestamp is represented by the
@@ -188,12 +207,12 @@ public TemporalAccessor resolve(
                     nanos = 1_000_000_000 + nanos;
                 }
             } else {
-                seconds = secondsAndMillis / 1_000;
-                nanos = secondsAndMillis % 1000 * 1_000_000;
+                seconds = secondsAndUnits / unitsPerSecond;
+                nanos = secondsAndUnits % unitsPerSecond * nanosPerUnit;
 
-                if (nanosOfMilli != null) {
+                if (nanosOfUnit != null) {
                     // aggregate fractional part of the input
-                    nanos += nanosOfMilli;
+                    nanos += nanosOfUnit;
                 }
             }
             fieldValues.put(ChronoField.INSTANT_SECONDS, seconds);
@@ -207,6 +226,24 @@ public TemporalAccessor resolve(
             }
             return null;
         }
+    }
+
+    private static final EpochField NANOS_OF_MICRO = new EpochField(ChronoUnit.NANOS, ChronoUnit.MICROS, ValueRange.of(0, 999)) {
+        @Override
+        public boolean isSupportedBy(TemporalAccessor temporal) {
+            return temporal.isSupported(ChronoField.INSTANT_SECONDS)
+                && temporal.isSupported(ChronoField.NANO_OF_SECOND)
+                && temporal.getLong(ChronoField.NANO_OF_SECOND) % 1_000 != 0;
+        }
+
+        @Override
+        public long getFrom(TemporalAccessor temporal) {
+            if (temporal.getLong(ChronoField.INSTANT_SECONDS) < 0) {
+                return (1_000_000_000 - temporal.getLong(ChronoField.NANO_OF_SECOND)) % 1_000;
+            } else {
+                return temporal.getLong(ChronoField.NANO_OF_SECOND) % 1_000;
+            }
+        }
     };
 
     private static final EpochField NANOS_OF_MILLI = new EpochField(ChronoUnit.NANOS, ChronoUnit.MILLIS, ValueRange.of(0, 999_999)) {
@@ -227,6 +264,23 @@ public long getFrom(TemporalAccessor temporal) {
         }
     };
 
+    // Millis as absolute values. Negative millis are encoded by having a NEGATIVE SIGN.
+    private static final EpochField MILLIS_ABS = new AbsoluteEpochField(
+        ChronoUnit.MILLIS,
+        1_000L,
+        1_000_000L,
+        ChronoField.MILLI_OF_SECOND,
+        NANOS_OF_MILLI
+    );
+
+    private static final EpochField MICROS = new AbsoluteEpochField(
+        ChronoUnit.MICROS,
+        1_000_000L,
+        1_000L,
+        ChronoField.MICRO_OF_SECOND,
+        NANOS_OF_MICRO
+    );
+
     // this supports seconds without any fraction
     private static final DateTimeFormatter SECONDS_FORMATTER1 = new DateTimeFormatterBuilder().appendValue(SECONDS, 1, 19, SignStyle.NORMAL)
         .optionalStart() // optional is used so isSupported will be called when printing
@@ -261,6 +315,21 @@ public long getFrom(TemporalAccessor temporal) {
         .appendLiteral('.')
         .toFormatter(Locale.ROOT);
 
+    // this supports microseconds
+    private static final DateTimeFormatter MICROSECONDS_FORMATTER1 = new DateTimeFormatterBuilder().optionalStart()
+        .appendText(SIGN, SIGN_FORMATTER_LOOKUP) // field is only created in the presence of a '-' char.
+        .optionalEnd()
+        .appendValue(MICROS, 1, 19, SignStyle.NOT_NEGATIVE)
+        .optionalStart()
+        .appendFraction(NANOS_OF_MICRO, 0, 3, true)
+        .optionalEnd()
+        .toFormatter(Locale.ROOT);
+
+    // this supports microseconds ending in dot
+    private static final DateTimeFormatter MICROSECONDS_FORMATTER2 = new DateTimeFormatterBuilder().append(MICROSECONDS_FORMATTER1)
+        .appendLiteral('.')
+        .toFormatter(Locale.ROOT);
+
     static final DateFormatter SECONDS_FORMATTER = new JavaDateFormatter(
         "epoch_second",
         SECONDS_FORMATTER1,
@@ -277,6 +346,14 @@ public long getFrom(TemporalAccessor temporal) {
         MILLISECONDS_FORMATTER2
     );
 
+    static final DateFormatter MICROS_FORMATTER = new JavaDateFormatter(
+        "epoch_micros",
+        MICROSECONDS_FORMATTER1,
+        (builder, parser) -> builder.parseDefaulting(EpochTime.NANOS_OF_MICRO, 999L),
+        MICROSECONDS_FORMATTER1,
+        MICROSECONDS_FORMATTER2
+    );
+
     /**
      * Base class for an epoch field
      *
diff --git a/server/src/main/java/org/opensearch/common/time/FormatNames.java b/server/src/main/java/org/opensearch/common/time/FormatNames.java
@@ -91,6 +91,7 @@ public enum FormatNames {
     YEAR_MONTH_DAY("yearMonthDay", "year_month_day"),
     EPOCH_SECOND(null, "epoch_second"),
     EPOCH_MILLIS(null, "epoch_millis"),
+    EPOCH_MICROS(null, "epoch_micros"),
     // strict date formats here, must be at least 4 digits for year and two for months and two for day"
     STRICT_BASIC_WEEK_DATE("strictBasicWeekDate", "strict_basic_week_date"),
     STRICT_BASIC_WEEK_DATE_TIME("strictBasicWeekDateTime", "strict_basic_week_date_time"),
diff --git a/server/src/test/java/org/opensearch/common/joda/JavaJodaTimeDuellingTests.java b/server/src/test/java/org/opensearch/common/joda/JavaJodaTimeDuellingTests.java
@@ -782,7 +782,8 @@ public void testSamePrinterOutput() {
         for (FormatNames format : FormatNames.values()) {
             if (format == FormatNames.ISO8601
                 || format == FormatNames.STRICT_DATE_OPTIONAL_TIME_NANOS
-                || format == FormatNames.RFC3339_LENIENT) {
+                || format == FormatNames.RFC3339_LENIENT
+                || format == FormatNames.EPOCH_MICROS) {
                 // Nanos aren't supported by joda
                 continue;
             }
diff --git a/server/src/test/java/org/opensearch/common/time/DateFormattersTests.java b/server/src/test/java/org/opensearch/common/time/DateFormattersTests.java
