Specify timestamp field with timefield in timechart command

core/src/main/java/org/opensearch/sql/ast/tree/Chart.java

@@ -97,16 +97,14 @@ private UnresolvedPlan transformPerFunction() {
 
     PerFunction perFunc = perFuncOpt.get();
     // For chart, the rowSplit should contain the span information
-    UnresolvedExpression spanExpr = rowSplit;
-    if (rowSplit instanceof Alias) {
-      spanExpr = ((Alias) rowSplit).getDelegated();
-    }
+    UnresolvedExpression spanExpr =
+        rowSplit instanceof Alias ? ((Alias) rowSplit).getDelegated() : rowSplit;
     if (!(spanExpr instanceof Span)) {
       return this; // Cannot transform without span information
     }
 
     Span span = (Span) spanExpr;
-    Field spanStartTime = AstDSL.implicitTimestampField();
+    Field spanStartTime = (Field) span.getField();
     Function spanEndTime = timestampadd(span.getUnit(), span.getValue(), spanStartTime);
     Function spanMillis = timestampdiff(MILLISECOND, spanStartTime, spanEndTime);
     final int SECOND_IN_MILLISECOND = 1000;

docs/user/ppl/cmd/timechart.rst

@@ -16,7 +16,9 @@ Description
 Syntax
 ======
 
-timechart [span=<time_interval>] [limit=<number>] [useother=<boolean>] <aggregation_function> [by <field>]
+timechart [timefield=<field_name>] [span=<time_interval>] [limit=<number>] [useother=<boolean>] <aggregation_function> [by <field>]
+
+* timefield:  optional. Specifies the timestamp field to use for time interval grouping. **Default**: ``@timestamp``.
 
 * span: optional. Specifies the time interval for grouping data. **Default:** 1m (1 minute).
 
@@ -92,7 +94,7 @@ Return type: DOUBLE
 Notes
 =====
 
-* The ``timechart`` command requires a timestamp field named ``@timestamp`` in the data.
+* The ``timechart`` command requires a timestamp field in the data. By default, it uses the ``@timestamp`` field, but you can specify a different field using the ``timefield`` parameter.
 * Results are returned in an unpivoted format with separate rows for each time-field combination that has data.
 * Only combinations with actual data are included in the results - empty combinations are omitted rather than showing null or zero values.
 * The "top N" values for the ``limit`` parameter are selected based on the sum of values across all time intervals for each distinct field value.

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteTimechartCommandIT.java

@@ -13,6 +13,7 @@
 import org.json.JSONObject;
 import org.junit.jupiter.api.Test;
 import org.opensearch.client.ResponseException;
+import org.opensearch.sql.common.utils.StringUtils;
 import org.opensearch.sql.ppl.PPLIntegTestCase;
 
 public class CalciteTimechartCommandIT extends PPLIntegTestCase {
@@ -64,7 +65,7 @@ public void testTimechartWithMinuteSpanAndGroupBy() throws IOException {
   }
 
   @Test
-  public void testTimechartWithoutTimestampField() throws IOException {
+  public void testTimechartWithoutTimestampField() {
     Throwable exception =
         assertThrows(
             ResponseException.class,
@@ -74,6 +75,16 @@ public void testTimechartWithoutTimestampField() throws IOException {
     verifyErrorMessageContains(exception, "Field [@timestamp] not found.");
   }
 
+  @Test
+  public void testTimechartWithCustomTimeField() throws IOException {
+    JSONObject result =
+        executeQuery(
+            StringUtils.format(
+                "source=%s | timechart timefield=birthdate span=1year count()", TEST_INDEX_BANK));
+    verifySchema(result, schema("birthdate", "timestamp"), schema("count()", "bigint"));
+    verifyDataRows(result, rows("2017-01-01 00:00:00", 2), rows("2018-01-01 00:00:00", 5));
+  }
+
   @Test
   public void testTimechartWithMinuteSpanNoGroupBy() throws IOException {
     JSONObject result = executeQuery("source=events | timechart span=1m avg(cpu_usage)");

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteTimechartPerFunctionIT.java

@@ -5,6 +5,7 @@
 
 package org.opensearch.sql.calcite.remote;
 
+import static org.opensearch.sql.util.MatcherUtils.closeTo;
 import static org.opensearch.sql.util.MatcherUtils.rows;
 import static org.opensearch.sql.util.MatcherUtils.schema;
 import static org.opensearch.sql.util.MatcherUtils.verifyDataRows;
@@ -13,6 +14,8 @@
 import java.io.IOException;
 import org.json.JSONObject;
 import org.junit.jupiter.api.Test;
+import org.opensearch.sql.common.utils.StringUtils;
+import org.opensearch.sql.legacy.TestsConstants;
 import org.opensearch.sql.ppl.PPLIntegTestCase;
 
 public class CalciteTimechartPerFunctionIT extends PPLIntegTestCase {
@@ -24,6 +27,7 @@ public void init() throws Exception {
     disallowCalciteFallback();
 
     loadIndex(Index.EVENTS_TRAFFIC);
+    loadIndex(Index.BANK);
   }
 
   @Test
@@ -208,4 +212,26 @@ public void testTimechartPerDayWithByClause() throws IOException {
         rows("2025-09-08 10:02:00", "server1", 43200.0), // 60 * 720
         rows("2025-09-08 10:02:00", "server2", 129600.0)); // 180 * 720
   }
+
+  @Test
+  public void testTimechartPerMonthWithSpecifiedSpan() throws IOException {
+    JSONObject result =
+        executeQuery(
+            StringUtils.format(
+                "source=%s | timechart timefield=birthdate span=1month per_day(balance) by gender",
+                TestsConstants.TEST_INDEX_BANK));
+    verifySchema(
+        result,
+        schema("birthdate", "timestamp"),
+        schema("gender", "string"),
+        schema("per_day(balance)", "double"));
+    verifyDataRows(
+        result,
+        closeTo("2017-10-01 00:00:00", "M", 1265.3225806451612),
+        closeTo("2017-11-01 00:00:00", "M", 189.53333333333333),
+        closeTo("2018-06-01 00:00:00", "F", 1094.6),
+        closeTo("2018-06-01 00:00:00", "M", 547.2666666666667),
+        closeTo("2018-08-01 00:00:00", "F", 2858.9032258064517),
+        closeTo("2018-11-01 00:00:00", "M", 139.33333333333334));
+  }
 }

ppl/src/main/antlr/OpenSearchPPLLexer.g4

@@ -145,6 +145,7 @@ LIMIT:                              'LIMIT';
 USEOTHER:                           'USEOTHER';
 OTHERSTR:                           'OTHERSTR';
 NULLSTR:                            'NULLSTR';
+TIMEFIELD:                          'TIMEFIELD';
 INPUT:                              'INPUT';
 OUTPUT:                             'OUTPUT';
 PATH:                               'PATH';

ppl/src/main/antlr/OpenSearchPPLParser.g4

@@ -328,6 +328,7 @@ timechartParameter
    : LIMIT EQUAL integerLiteral
    | SPAN EQUAL spanLiteral
    | USEOTHER EQUAL (booleanLiteral | ident)
+   | TIMEFIELD EQUAL (ident | stringLiteral)
    ;
 
 spanLiteral
@@ -1570,6 +1571,7 @@ searchableKeyWord
    | SED
    | MAX_MATCH
    | OFFSET_FIELD
+   | TIMEFIELD
    | patternMethod
    | patternMode
    // AGGREGATIONS AND WINDOW

ppl/src/main/java/org/opensearch/sql/ppl/parser/AstBuilder.java

@@ -63,8 +63,6 @@
 import org.opensearch.sql.ast.expression.SearchAnd;
 import org.opensearch.sql.ast.expression.SearchExpression;
 import org.opensearch.sql.ast.expression.SearchGroup;
-import org.opensearch.sql.ast.expression.Span;
-import org.opensearch.sql.ast.expression.SpanUnit;
 import org.opensearch.sql.ast.expression.UnresolvedArgument;
 import org.opensearch.sql.ast.expression.UnresolvedExpression;
 import org.opensearch.sql.ast.expression.WindowFrame;
@@ -770,41 +768,28 @@ private List<UnresolvedExpression> parseAggTerms(
   /** Timechart command. */
   @Override
   public UnresolvedPlan visitTimechartCommand(OpenSearchPPLParser.TimechartCommandContext ctx) {
-    UnresolvedExpression binExpression =
-        AstDSL.span(AstDSL.implicitTimestampField(), AstDSL.intLiteral(1), SpanUnit.m);
-    Integer limit = 10;
-    Boolean useOther = true;
-    // Process timechart parameters
-    for (OpenSearchPPLParser.TimechartParameterContext paramCtx : ctx.timechartParameter()) {
-      UnresolvedExpression param = internalVisitExpression(paramCtx);
-      if (param instanceof Span) {
-        binExpression = param;
-      } else if (param instanceof Literal literal) {
-        if (DataType.BOOLEAN.equals(literal.getType())) {
-          useOther = (Boolean) literal.getValue();
-        } else if (DataType.INTEGER.equals(literal.getType())
-            || DataType.LONG.equals(literal.getType())) {
-          limit = (Integer) literal.getValue();
-        }
-      }
-    }
+    List<Argument> arguments = ArgumentFactory.getArgumentList(ctx, expressionBuilder);
+    ArgumentMap argMap = ArgumentMap.of(arguments);
+    Literal spanLiteral = argMap.getOrDefault("spanliteral", AstDSL.stringLiteral("1m"));
+    String timeFieldName =
+        Optional.ofNullable(argMap.get("timefield"))
+            .map(l -> (String) l.getValue())
+            .orElse(OpenSearchConstants.IMPLICIT_FIELD_TIMESTAMP);
+    Field spanField = AstDSL.field(timeFieldName);
+    Alias span =
+        AstDSL.alias(timeFieldName, AstDSL.spanFromSpanLengthLiteral(spanField, spanLiteral));
     UnresolvedExpression aggregateFunction = parseAggTerms(List.of(ctx.statsAggTerm())).getFirst();
-
     UnresolvedExpression byField =
-        ctx.fieldExpression() != null ? internalVisitExpression(ctx.fieldExpression()) : null;
-    List<Argument> arguments =
-        List.of(
-            new Argument("limit", AstDSL.intLiteral(limit)),
-            new Argument("useother", AstDSL.booleanLiteral(useOther)));
-    binExpression = AstDSL.alias(OpenSearchConstants.IMPLICIT_FIELD_TIMESTAMP, binExpression);
-    if (byField != null) {
-      byField =
-          AstDSL.alias(
-              StringUtils.unquoteIdentifier(getTextInQuery(ctx.fieldExpression())), byField);
-    }
+        Optional.ofNullable(ctx.fieldExpression())
+            .map(
+                f ->
+                    AstDSL.alias(
+                        StringUtils.unquoteIdentifier(getTextInQuery(f)),
+                        internalVisitExpression(f)))
+            .orElse(null);
     return Chart.builder()
         .aggregationFunction(aggregateFunction)
-        .rowSplit(binExpression)
+        .rowSplit(span)
         .columnSplit(byField)
         .arguments(arguments)
         .build();

ppl/src/main/java/org/opensearch/sql/ppl/parser/AstExpressionBuilder.java

@@ -757,7 +757,7 @@ public UnresolvedExpression visitMaxOption(OpenSearchPPLParser.MaxOptionContext
     return new Argument("max", (Literal) this.visit(ctx.integerLiteral()));
   }
 
-  private QualifiedName visitIdentifiers(List<? extends ParserRuleContext> ctx) {
+  public QualifiedName visitIdentifiers(List<? extends ParserRuleContext> ctx) {
     return new QualifiedName(
         ctx.stream()
             .map(RuleContext::getText)
@@ -995,47 +995,6 @@ public UnresolvedExpression visitTimeModifierValue(
     return AstDSL.stringLiteral(osDateMathExpression);
   }
 
-  @Override
-  public UnresolvedExpression visitTimechartParameter(
-      OpenSearchPPLParser.TimechartParameterContext ctx) {
-    UnresolvedExpression timechartParameter;
-    if (ctx.SPAN() != null) {
-      // Convert span=1h to span(@timestamp, 1h)
-      Literal spanLiteral = (Literal) visit(ctx.spanLiteral());
-      timechartParameter =
-          AstDSL.spanFromSpanLengthLiteral(AstDSL.implicitTimestampField(), spanLiteral);
-    } else if (ctx.LIMIT() != null) {
-      Literal limit = (Literal) visit(ctx.integerLiteral());
-      if ((Integer) limit.getValue() < 0) {
-        throw new IllegalArgumentException("Limit must be a non-negative number");
-      }
-      timechartParameter = limit;
-    } else if (ctx.USEOTHER() != null) {
-      UnresolvedExpression useOther;
-      if (ctx.booleanLiteral() != null) {
-        useOther = visit(ctx.booleanLiteral());
-      } else if (ctx.ident() != null) {
-        QualifiedName ident = visitIdentifiers(List.of(ctx.ident()));
-        String useOtherValue = ident.toString();
-        if ("true".equalsIgnoreCase(useOtherValue) || "t".equalsIgnoreCase(useOtherValue)) {
-          useOther = AstDSL.booleanLiteral(true);
-        } else if ("false".equalsIgnoreCase(useOtherValue) || "f".equalsIgnoreCase(useOtherValue)) {
-          useOther = AstDSL.booleanLiteral(false);
-        } else {
-          throw new IllegalArgumentException(
-              "Invalid useOther value: " + ctx.ident().getText() + ". Expected true/false or t/f");
-        }
-      } else {
-        throw new IllegalArgumentException("value for useOther must be a boolean or identifier");
-      }
-      timechartParameter = useOther;
-    } else {
-      throw new IllegalArgumentException(
-          String.format("A parameter of timechart must be a span, limit or useOther, got %s", ctx));
-    }
-    return timechartParameter;
-  }
-
   /**
    * Process time range expressions (EARLIEST='value' or LATEST='value') It creates a Comparison
    * filter like @timestamp >= timeModifierValue

ppl/src/main/java/org/opensearch/sql/ppl/utils/ArgumentFactory.java

@@ -33,6 +33,7 @@
 import org.opensearch.sql.ppl.antlr.parser.OpenSearchPPLParser.SortFieldContext;
 import org.opensearch.sql.ppl.antlr.parser.OpenSearchPPLParser.StreamstatsCommandContext;
 import org.opensearch.sql.ppl.antlr.parser.OpenSearchPPLParser.SuffixSortFieldContext;
+import org.opensearch.sql.ppl.parser.AstExpressionBuilder;
 
 /** Util class to get all arguments as a list from the PPL command. */
 public class ArgumentFactory {
@@ -245,6 +246,60 @@ public static List<Argument> getArgumentList(ChartCommandContext ctx) {
     return arguments;
   }
 
+  public static List<Argument> getArgumentList(
+      OpenSearchPPLParser.TimechartCommandContext timechartCtx,
+      AstExpressionBuilder expressionBuilder) {
+    List<Argument> arguments = new ArrayList<>();
+    for (OpenSearchPPLParser.TimechartParameterContext ctx : timechartCtx.timechartParameter()) {
+      if (ctx.SPAN() != null) {
+        arguments.add(
+            new Argument("spanliteral", (Literal) expressionBuilder.visit(ctx.spanLiteral())));
+      } else if (ctx.LIMIT() != null) {
+        Literal limit = getArgumentValue(ctx.integerLiteral());
+        if ((Integer) limit.getValue() < 0) {
+          throw new IllegalArgumentException("Limit must be a non-negative number");
+        }
+        arguments.add(new Argument("limit", limit));
+      } else if (ctx.USEOTHER() != null) {
+        Literal useOther;
+        if (ctx.booleanLiteral() != null) {
+          useOther = getArgumentValue(ctx.booleanLiteral());
+        } else if (ctx.ident() != null) {
+          String identLiteral = expressionBuilder.visitIdentifiers(List.of(ctx.ident())).toString();
+          if ("true".equalsIgnoreCase(identLiteral) || "t".equalsIgnoreCase(identLiteral)) {
+            useOther = AstDSL.booleanLiteral(true);
+          } else if ("false".equalsIgnoreCase(identLiteral) || "f".equalsIgnoreCase(identLiteral)) {
+            useOther = AstDSL.booleanLiteral(false);
+          } else {
+            throw new IllegalArgumentException(
+                "Invalid useOther value: "
+                    + ctx.ident().getText()
+                    + ". Expected true/false or t/f");
+          }
+        } else {
+          throw new IllegalArgumentException("value for useOther must be a boolean or identifier");
+        }
+        arguments.add(new Argument("useother", useOther));
+      } else if (ctx.TIMEFIELD() != null) {
+        Literal timeField;
+        if (ctx.ident() != null) {
+          timeField =
+              AstDSL.stringLiteral(
+                  expressionBuilder.visitIdentifiers(List.of(ctx.ident())).toString());
+        } else {
+          timeField = getArgumentValue(ctx.stringLiteral());
+        }
+        arguments.add(new Argument("timefield", timeField));
+      } else {
+        throw new IllegalArgumentException(
+            String.format(
+                "A parameter of timechart must be a span, limit, useother, or timefield, got %s",
+                ctx));
+      }
+    }
+    return arguments;
+  }
+
   /**
    * Get list of {@link Argument}.
    *