strftime function implementation

core/src/main/java/org/opensearch/sql/analysis/ExpressionAnalyzer.java

@@ -17,6 +17,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
+import java.util.Set;
 import java.util.stream.Collectors;
 import lombok.Getter;
 import org.opensearch.sql.analysis.symbol.Namespace;
@@ -53,6 +54,7 @@
 import org.opensearch.sql.ast.expression.subquery.ExistsSubquery;
 import org.opensearch.sql.ast.expression.subquery.InSubquery;
 import org.opensearch.sql.ast.expression.subquery.ScalarSubquery;
+import org.opensearch.sql.calcite.utils.CalciteUtils;
 import org.opensearch.sql.data.model.ExprValueUtils;
 import org.opensearch.sql.data.type.ExprCoreType;
 import org.opensearch.sql.data.type.ExprType;
@@ -191,6 +193,7 @@ public Expression visitRelevanceFieldList(RelevanceFieldList node, AnalysisConte
   @Override
   public Expression visitFunction(Function node, AnalysisContext context) {
     FunctionName functionName = FunctionName.of(node.getFuncName());
+    validateCalciteOnlyFunction(functionName);
     List<Expression> arguments =
         node.getFuncArgs().stream()
             .map(
@@ -208,6 +211,34 @@ public Expression visitFunction(Function node, AnalysisContext context) {
         repository.compile(context.getFunctionProperties(), functionName, arguments);
   }
 
+  /**
+   * Validates that functions requiring Calcite engine are not used without it.
+   *
+   * @param functionName The function name to validate
+   */
+  private void validateCalciteOnlyFunction(FunctionName functionName) {
+    if (isCalciteOnlyFunction(functionName)) {
+      throw CalciteUtils.getOnlyForCalciteException(functionName.getFunctionName().toUpperCase());
+    }
+  }
+
+  /**
+   * Checks if a function requires Calcite engine to be enabled.
+   *
+   * @param functionName The function name to check
+   * @return true if the function requires Calcite, false otherwise
+   */
+  private boolean isCalciteOnlyFunction(FunctionName functionName) {
+    // Set of functions that are only supported with Calcite engine
+    Set<String> calciteOnlyFunctions =
+        ImmutableSet.of(
+            BuiltinFunctionName.REGEX_MATCH.getName().getFunctionName(),
+            BuiltinFunctionName.STRFTIME.getName().getFunctionName());
+
+    return calciteOnlyFunctions.stream()
+        .anyMatch(f -> f.equalsIgnoreCase(functionName.getFunctionName()));
+  }
+
   @SuppressWarnings("unchecked")
   @Override
   public Expression visitWindowFunction(WindowFunction node, AnalysisContext context) {

core/src/main/java/org/opensearch/sql/expression/datetime/StrftimeFormatterUtil.java

@@ -0,0 +1,252 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.expression.datetime;
+
+import com.google.common.collect.ImmutableMap;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.TextStyle;
+import java.time.temporal.IsoFields;
+import java.time.temporal.WeekFields;
+import java.util.Locale;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import org.opensearch.sql.data.model.ExprStringValue;
+import org.opensearch.sql.data.model.ExprValue;
+
+/** Utility class for POSIX-style strftime formatting. */
+public class StrftimeFormatterUtil {
+
+  // Constants
+  private static final String PERCENT_PLACEHOLDER = "\u0001PERCENT\u0001";
+  private static final String PERCENT_LITERAL = "%%";
+  private static final int DEFAULT_NANOSECOND_PRECISION = 9;
+  private static final int DEFAULT_MILLISECOND_PRECISION = 3;
+  private static final int MICROSECOND_PRECISION = 6;
+  private static final long NANOS_PER_SECOND = 1_000_000_000L;
+  private static final long MILLIS_PER_SECOND = 1000L;
+  private static final long MAX_UNIX_TIMESTAMP = 32536771199L;
+  private static final int UNIX_TIMESTAMP_DIGITS = 10;
+
+  // Pattern to match %N and %Q with optional precision digit
+  private static final Pattern SUBSECOND_PATTERN = Pattern.compile("%(\\d)?([NQ])");
+
+  @FunctionalInterface
+  private interface StrftimeFormatHandler {
+    String format(ZonedDateTime dateTime);
+  }
+
+  private static final Map<String, StrftimeFormatHandler> STRFTIME_HANDLERS = buildHandlers();
+
+  private static Map<String, StrftimeFormatHandler> buildHandlers() {
+    return ImmutableMap.<String, StrftimeFormatHandler>builder()
+        // Date and time combinations
+        .put(
+            "%c",
+            dt -> dt.format(DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss yyyy", Locale.ROOT)))
+        .put(
+            "%+",
+            dt ->
+                dt.format(DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss zzz yyyy", Locale.ROOT)))
+
+        // Time formats
+        .put("%Ez", StrftimeFormatterUtil::formatTimezoneOffsetMinutes)
+        .put("%f", dt -> String.format("%06d", dt.getNano() / 1000))
+        .put("%H", dt -> dt.format(DateTimeFormatter.ofPattern("HH", Locale.ROOT)))
+        .put("%I", dt -> dt.format(DateTimeFormatter.ofPattern("hh", Locale.ROOT)))
+        .put("%k", dt -> String.format("%2d", dt.getHour()))
+        .put("%M", dt -> dt.format(DateTimeFormatter.ofPattern("mm", Locale.ROOT)))
+        .put("%p", dt -> dt.format(DateTimeFormatter.ofPattern("a", Locale.ROOT)))
+        .put("%S", dt -> dt.format(DateTimeFormatter.ofPattern("ss", Locale.ROOT)))
+        .put("%s", dt -> String.valueOf(dt.toEpochSecond()))
+        .put("%T", dt -> dt.format(DateTimeFormatter.ofPattern("HH:mm:ss", Locale.ROOT)))
+        .put("%X", dt -> dt.format(DateTimeFormatter.ofPattern("HH:mm:ss", Locale.ROOT)))
+
+        // Timezone formats
+        .put("%Z", dt -> dt.getZone().getDisplayName(TextStyle.SHORT, Locale.ROOT))
+        .put("%z", dt -> dt.format(DateTimeFormatter.ofPattern("xx", Locale.ROOT)))
+        .put("%:z", dt -> dt.format(DateTimeFormatter.ofPattern("xxx", Locale.ROOT)))
+        .put("%::z", dt -> dt.format(DateTimeFormatter.ofPattern("xxx:ss", Locale.ROOT)))
+        .put("%:::z", dt -> dt.format(DateTimeFormatter.ofPattern("x", Locale.ROOT)))
+
+        // Date formats
+        .put("%F", dt -> dt.format(DateTimeFormatter.ofPattern("yyyy-MM-dd", Locale.ROOT)))
+        .put("%x", dt -> dt.format(DateTimeFormatter.ofPattern("MM/dd/yyyy", Locale.ROOT)))
+
+        // Weekday formats
+        .put("%A", dt -> dt.format(DateTimeFormatter.ofPattern("EEEE", Locale.ROOT)))
+        .put("%a", dt -> dt.format(DateTimeFormatter.ofPattern("EEE", Locale.ROOT)))
+        .put("%w", dt -> String.valueOf(dt.getDayOfWeek().getValue() % 7))
+
+        // Day formats
+        .put("%d", dt -> dt.format(DateTimeFormatter.ofPattern("dd", Locale.ROOT)))
+        .put("%e", dt -> String.format("%2d", dt.getDayOfMonth()))
+        .put("%j", dt -> dt.format(DateTimeFormatter.ofPattern("DDD", Locale.ROOT)))
+
+        // Week formats
+        .put("%V", dt -> String.format("%02d", dt.get(IsoFields.WEEK_OF_WEEK_BASED_YEAR)))
+        .put("%U", dt -> String.format("%02d", dt.get(WeekFields.SUNDAY_START.weekOfYear()) - 1))
+
+        // Month formats
+        .put("%b", dt -> dt.format(DateTimeFormatter.ofPattern("MMM", Locale.ROOT)))
+        .put("%B", dt -> dt.format(DateTimeFormatter.ofPattern("MMMM", Locale.ROOT)))
+        .put("%m", dt -> dt.format(DateTimeFormatter.ofPattern("MM", Locale.ROOT)))
+
+        // Year formats
+        .put("%C", dt -> String.format("%02d", dt.getYear() / 100))
+        .put("%g", dt -> String.format("%02d", dt.get(IsoFields.WEEK_BASED_YEAR) % 100))
+        .put("%G", dt -> String.format("%04d", dt.get(IsoFields.WEEK_BASED_YEAR)))
+        .put("%y", dt -> dt.format(DateTimeFormatter.ofPattern("yy", Locale.ROOT)))
+        .put("%Y", dt -> dt.format(DateTimeFormatter.ofPattern("yyyy", Locale.ROOT)))
+
+        // Literal percent
+        .put(PERCENT_LITERAL, dt -> "%")
+        .build();
+  }
+
+  private StrftimeFormatterUtil() {}
+
+  /**
+   * Format a ZonedDateTime using STRFTIME format specifiers.
+   *
+   * @param dateTime The ZonedDateTime to format
+   * @param formatString The STRFTIME format string
+   * @return Formatted string as ExprValue, or ExprNullValue if inputs are null
+   */
+  public static ExprValue formatZonedDateTime(ZonedDateTime dateTime, String formatString) {
+    String result = processFormatString(formatString, dateTime);
+    return new ExprStringValue(result);
+  }
+
+  /** Process the format string and replace all format specifiers. */
+  private static String processFormatString(String formatString, ZonedDateTime dateTime) {
+    // Handle %N and %Q with precision first
+    String result = handleSubSecondFormats(formatString, dateTime);
+
+    // Escape %% by replacing with placeholder
+    result = result.replace(PERCENT_LITERAL, PERCENT_PLACEHOLDER);
+
+    // Replace all other format specifiers
+    result = replaceFormatSpecifiers(result, dateTime);
+
+    // Restore literal percent signs
+    return result.replace(PERCENT_PLACEHOLDER, "%");
+  }
+
+  /** Replace all format specifiers in the string. */
+  private static String replaceFormatSpecifiers(String input, ZonedDateTime dateTime) {
+    String result = input;
+    for (Map.Entry<String, StrftimeFormatHandler> entry : STRFTIME_HANDLERS.entrySet()) {
+      String specifier = entry.getKey();
+      if (result.contains(specifier)) {
+        String replacement = entry.getValue().format(dateTime);
+        result = result.replace(specifier, replacement);
+      }
+    }
+    return result;
+  }
+
+  /** Handle %N and %Q subsecond formats with optional precision. */
+  private static String handleSubSecondFormats(String format, ZonedDateTime dateTime) {
+    StringBuilder result = new StringBuilder();
+    Matcher matcher = SUBSECOND_PATTERN.matcher(format);
+
+    while (matcher.find()) {
+      String precisionStr = matcher.group(1);
+      String type = matcher.group(2);
+
+      int precision = parsePrecision(precisionStr, type);
+      String replacement = formatSubseconds(dateTime, type, precision);
+
+      matcher.appendReplacement(result, replacement);
+    }
+    matcher.appendTail(result);
+
+    return result.toString();
+  }
+
+  /** Parse precision value for subsecond formats. */
+  private static int parsePrecision(String precisionStr, String type) {
+    if (precisionStr != null) {
+      return Integer.parseInt(precisionStr);
+    }
+    // Default: %N=9 (nanoseconds), %Q=3 (milliseconds)
+    return "N".equals(type) ? DEFAULT_NANOSECOND_PRECISION : DEFAULT_MILLISECOND_PRECISION;
+  }
+
+  /** Format subseconds based on type and precision. */
+  private static String formatSubseconds(ZonedDateTime dateTime, String type, int precision) {
+    if ("N".equals(type)) {
+      // %N - subsecond digits (nanoseconds)
+      return formatNanoseconds(dateTime.getNano(), precision);
+    } else {
+      // %Q - subsecond component
+      return formatQSubseconds(dateTime, precision);
+    }
+  }
+
+  /** Format nanoseconds with specified precision. */
+  private static String formatNanoseconds(long nanos, int precision) {
+    double scaled = (double) nanos / NANOS_PER_SECOND;
+    long truncated = (long) (scaled * Math.pow(10, precision));
+    return String.format("%0" + precision + "d", truncated);
+  }
+
+  /** Format Q-type subseconds based on precision. */
+  private static String formatQSubseconds(ZonedDateTime dateTime, int precision) {
+    switch (precision) {
+      case MICROSECOND_PRECISION:
+        // Microseconds
+        long micros = dateTime.getNano() / 1000;
+        return String.format("%06d", micros);
+
+      case DEFAULT_NANOSECOND_PRECISION:
+        // Nanoseconds
+        return String.format("%09d", dateTime.getNano());
+
+      default:
+        // Default to milliseconds
+        long millis = dateTime.toInstant().toEpochMilli() % MILLIS_PER_SECOND;
+        return String.format("%03d", millis);
+    }
+  }
+
+  /** Format timezone offset in minutes. */
+  private static String formatTimezoneOffsetMinutes(ZonedDateTime dt) {
+    int offsetMinutes = dt.getOffset().getTotalSeconds() / 60;
+    return String.format("%+d", offsetMinutes);
+  }
+
+  /**
+   * Extract the first 10 digits from a timestamp to get UNIX seconds. This handles timestamps that
+   * may be in milliseconds or nanoseconds.
+   *
+   * @param timestamp The timestamp value
+   * @return UNIX timestamp in seconds
+   */
+  public static long extractUnixSeconds(double timestamp) {
+    // Return as-is if within valid Unix timestamp range
+    if (timestamp >= -MAX_UNIX_TIMESTAMP && timestamp <= MAX_UNIX_TIMESTAMP) {
+      return (long) timestamp;
+    }
+
+    // For larger absolute values, extract first 10 digits (assumes milliseconds/nanoseconds)
+    return extractFirstNDigits(timestamp, UNIX_TIMESTAMP_DIGITS);
+  }
+
+  /** Extract the first N digits from a number. */
+  private static long extractFirstNDigits(double value, int digits) {
+    boolean isNegative = value < 0;
+    long absValue = Math.abs((long) value);
+    String valueStr = String.valueOf(absValue);
+
+    long result =
+        valueStr.length() <= digits ? absValue : Long.parseLong(valueStr.substring(0, digits));
+
+    return isNegative ? -result : result;
+  }
+}

core/src/main/java/org/opensearch/sql/expression/function/BuiltinFunctionName.java

@@ -125,6 +125,7 @@ public enum BuiltinFunctionName {
   UTC_TIME(FunctionName.of("utc_time")),
   UTC_TIMESTAMP(FunctionName.of("utc_timestamp")),
   UNIX_TIMESTAMP(FunctionName.of("unix_timestamp")),
+  STRFTIME(FunctionName.of("strftime")),
   WEEK(FunctionName.of("week")),
   WEEKDAY(FunctionName.of("weekday")),
   WEEKOFYEAR(FunctionName.of("weekofyear")),

core/src/main/java/org/opensearch/sql/expression/function/PPLBuiltinOperators.java

@@ -76,6 +76,7 @@
 import org.opensearch.sql.expression.function.udf.datetime.LastDayFunction;
 import org.opensearch.sql.expression.function.udf.datetime.PeriodNameFunction;
 import org.opensearch.sql.expression.function.udf.datetime.SecToTimeFunction;
+import org.opensearch.sql.expression.function.udf.datetime.StrftimeFunction;
 import org.opensearch.sql.expression.function.udf.datetime.SysdateFunction;
 import org.opensearch.sql.expression.function.udf.datetime.TimestampAddFunction;
 import org.opensearch.sql.expression.function.udf.datetime.TimestampDiffFunction;
@@ -170,6 +171,7 @@ public class PPLBuiltinOperators extends ReflectiveSqlOperatorTable {
   public static final SqlOperator WEEKDAY = new WeekdayFunction().toUDF("WEEKDAY");
   public static final SqlOperator UNIX_TIMESTAMP =
       new UnixTimestampFunction().toUDF("UNIX_TIMESTAMP");
+  public static final SqlOperator STRFTIME = new StrftimeFunction().toUDF("STRFTIME");
   public static final SqlOperator TO_SECONDS = new ToSecondsFunction().toUDF("TO_SECONDS");
   public static final SqlOperator ADDTIME =
       adaptExprMethodWithPropertiesToUDF(

core/src/main/java/org/opensearch/sql/expression/function/PPLFuncImpTable.java

@@ -188,6 +188,7 @@
 import static org.opensearch.sql.expression.function.BuiltinFunctionName.STDDEV_POP;
 import static org.opensearch.sql.expression.function.BuiltinFunctionName.STDDEV_SAMP;
 import static org.opensearch.sql.expression.function.BuiltinFunctionName.STRCMP;
+import static org.opensearch.sql.expression.function.BuiltinFunctionName.STRFTIME;
 import static org.opensearch.sql.expression.function.BuiltinFunctionName.STR_TO_DATE;
 import static org.opensearch.sql.expression.function.BuiltinFunctionName.SUBDATE;
 import static org.opensearch.sql.expression.function.BuiltinFunctionName.SUBSTR;
@@ -755,6 +756,7 @@ void populate() {
       registerOperator(YEARWEEK, PPLBuiltinOperators.YEARWEEK);
       registerOperator(WEEKDAY, PPLBuiltinOperators.WEEKDAY);
       registerOperator(UNIX_TIMESTAMP, PPLBuiltinOperators.UNIX_TIMESTAMP);
+      registerOperator(STRFTIME, PPLBuiltinOperators.STRFTIME);
       registerOperator(TO_SECONDS, PPLBuiltinOperators.TO_SECONDS);
       registerOperator(TO_DAYS, PPLBuiltinOperators.TO_DAYS);
       registerOperator(ADDTIME, PPLBuiltinOperators.ADDTIME);