diff --git a/docs/user/ppl/cmd/timechart.rst b/docs/user/ppl/cmd/timechart.rst index 6aea1270f1..acb7697d71 100644 --- a/docs/user/ppl/cmd/timechart.rst +++ b/docs/user/ppl/cmd/timechart.rst @@ -22,10 +22,15 @@ Syntax .. code-block:: text - timechart [span=] [limit=] [useother=] [by ] + timechart [timefield=] [span=] [limit=] [useother=] [by ] **Parameters:** +* **timefield**: optional. Specifies the timestamp field to use for time interval grouping. + + * Default: ``@timestamp`` + * Specify a timestamp field for the time-based aggregation. + * **span**: optional. Specifies the time interval for grouping data. * Default: 1m (1 minute) @@ -105,7 +110,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. diff --git a/integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteTimechartCommandIT.java b/integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteTimechartCommandIT.java index 3b5c5f5547..73396ab31b 100644 --- a/integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteTimechartCommandIT.java +++ b/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)"); diff --git a/ppl/src/main/antlr/OpenSearchPPLLexer.g4 b/ppl/src/main/antlr/OpenSearchPPLLexer.g4 index b3587c319c..d6ee9dc793 100644 --- a/ppl/src/main/antlr/OpenSearchPPLLexer.g4 +++ b/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'; diff --git a/ppl/src/main/antlr/OpenSearchPPLParser.g4 b/ppl/src/main/antlr/OpenSearchPPLParser.g4 index d115f3dec3..76e9a52c39 100644 --- a/ppl/src/main/antlr/OpenSearchPPLParser.g4 +++ b/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 @@ -1562,6 +1563,7 @@ searchableKeyWord | SED | MAX_MATCH | OFFSET_FIELD + | TIMEFIELD | patternMethod | patternMode // AGGREGATIONS AND WINDOW diff --git a/ppl/src/main/java/org/opensearch/sql/ppl/parser/AstBuilder.java b/ppl/src/main/java/org/opensearch/sql/ppl/parser/AstBuilder.java index ed66682a98..2946dea16b 100644 --- a/ppl/src/main/java/org/opensearch/sql/ppl/parser/AstBuilder.java +++ b/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; @@ -760,41 +758,28 @@ private List 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 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 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(); diff --git a/ppl/src/main/java/org/opensearch/sql/ppl/parser/AstExpressionBuilder.java b/ppl/src/main/java/org/opensearch/sql/ppl/parser/AstExpressionBuilder.java index 05029de875..0c25053e00 100644 --- a/ppl/src/main/java/org/opensearch/sql/ppl/parser/AstExpressionBuilder.java +++ b/ppl/src/main/java/org/opensearch/sql/ppl/parser/AstExpressionBuilder.java @@ -749,7 +749,7 @@ public UnresolvedExpression visitMaxOption(OpenSearchPPLParser.MaxOptionContext return new Argument("max", (Literal) this.visit(ctx.integerLiteral())); } - private QualifiedName visitIdentifiers(List ctx) { + public QualifiedName visitIdentifiers(List ctx) { return new QualifiedName( ctx.stream() .map(RuleContext::getText) @@ -978,47 +978,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 diff --git a/ppl/src/main/java/org/opensearch/sql/ppl/utils/ArgumentFactory.java b/ppl/src/main/java/org/opensearch/sql/ppl/utils/ArgumentFactory.java index 41e9e91535..1a3ade3353 100644 --- a/ppl/src/main/java/org/opensearch/sql/ppl/utils/ArgumentFactory.java +++ b/ppl/src/main/java/org/opensearch/sql/ppl/utils/ArgumentFactory.java @@ -32,6 +32,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 { @@ -232,6 +233,60 @@ public static List getArgumentList(ChartCommandContext ctx) { return arguments; } + public static List getArgumentList( + OpenSearchPPLParser.TimechartCommandContext timechartCtx, + AstExpressionBuilder expressionBuilder) { + List 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}. * diff --git a/ppl/src/test/java/org/opensearch/sql/ppl/parser/AstBuilderTest.java b/ppl/src/test/java/org/opensearch/sql/ppl/parser/AstBuilderTest.java index aea0a6e289..2a842b2897 100644 --- a/ppl/src/test/java/org/opensearch/sql/ppl/parser/AstBuilderTest.java +++ b/ppl/src/test/java/org/opensearch/sql/ppl/parser/AstBuilderTest.java @@ -1249,10 +1249,7 @@ public void testTimechartWithPerSecondFunction() { alias("@timestamp", span(field("@timestamp"), intLiteral(1), SpanUnit.of("m")))) .columnSplit(null) .aggregationFunction(alias("per_second(a)", aggregate("sum", field("a")))) - .arguments( - exprList( - argument("limit", intLiteral(10)), - argument("useother", booleanLiteral(true)))) + .arguments(exprList()) .build(), let( field("per_second(a)"), @@ -1281,10 +1278,7 @@ public void testTimechartWithPerMinuteFunction() { alias("@timestamp", span(field("@timestamp"), intLiteral(1), SpanUnit.of("m")))) .columnSplit(null) .aggregationFunction(alias("per_minute(a)", aggregate("sum", field("a")))) - .arguments( - exprList( - argument("limit", intLiteral(10)), - argument("useother", booleanLiteral(true)))) + .arguments(exprList()) .build(), let( field("per_minute(a)"), @@ -1313,10 +1307,7 @@ public void testTimechartWithPerHourFunction() { alias("@timestamp", span(field("@timestamp"), intLiteral(1), SpanUnit.of("m")))) .columnSplit(null) .aggregationFunction(alias("per_hour(a)", aggregate("sum", field("a")))) - .arguments( - exprList( - argument("limit", intLiteral(10)), - argument("useother", booleanLiteral(true)))) + .arguments(exprList()) .build(), let( field("per_hour(a)"), @@ -1345,10 +1336,7 @@ public void testTimechartWithPerDayFunction() { alias("@timestamp", span(field("@timestamp"), intLiteral(1), SpanUnit.of("m")))) .columnSplit(null) .aggregationFunction(alias("per_day(a)", aggregate("sum", field("a")))) - .arguments( - exprList( - argument("limit", intLiteral(10)), - argument("useother", booleanLiteral(true)))) + .arguments(exprList()) .build(), let( field("per_day(a)"), diff --git a/ppl/src/test/java/org/opensearch/sql/ppl/parser/AstExpressionBuilderTest.java b/ppl/src/test/java/org/opensearch/sql/ppl/parser/AstExpressionBuilderTest.java index c5accc7f7c..ed8e32dbd3 100644 --- a/ppl/src/test/java/org/opensearch/sql/ppl/parser/AstExpressionBuilderTest.java +++ b/ppl/src/test/java/org/opensearch/sql/ppl/parser/AstExpressionBuilderTest.java @@ -1405,9 +1405,7 @@ public void testTimechartSpanParameter() { intLiteral(30), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(true)))) + .arguments(exprList(argument("spanliteral", stringLiteral("30m")))) .build()); } @@ -1425,9 +1423,7 @@ public void testTimechartLimitParameter() { intLiteral(1), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(100)), argument("useother", booleanLiteral(true)))) + .arguments(exprList(argument("limit", intLiteral(100)))) .build()); } @@ -1452,9 +1448,7 @@ public void testTimechartUseOtherWithBooleanLiteral() { intLiteral(1), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(true)))) + .arguments(exprList(argument("useother", booleanLiteral(true)))) .build()); assertEqual( @@ -1469,9 +1463,7 @@ public void testTimechartUseOtherWithBooleanLiteral() { intLiteral(1), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(false)))) + .arguments(exprList(argument("useother", booleanLiteral(false)))) .build()); } @@ -1489,9 +1481,7 @@ public void testTimechartUseOtherWithIdentifier() { intLiteral(1), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(true)))) + .arguments(exprList(argument("useother", booleanLiteral(true)))) .build()); assertEqual( @@ -1506,9 +1496,7 @@ public void testTimechartUseOtherWithIdentifier() { intLiteral(1), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(false)))) + .arguments(exprList(argument("useother", booleanLiteral(false)))) .build()); assertEqual( @@ -1523,9 +1511,7 @@ public void testTimechartUseOtherWithIdentifier() { intLiteral(1), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(true)))) + .arguments(exprList(argument("useother", booleanLiteral(true)))) .build()); assertEqual( @@ -1540,9 +1526,7 @@ public void testTimechartUseOtherWithIdentifier() { intLiteral(1), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(false)))) + .arguments(exprList(argument("useother", booleanLiteral(false)))) .build()); } @@ -1616,9 +1600,7 @@ public void testVisitSpanLiteral() { intLiteral(1), SpanUnit.H))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(true)))) + .arguments(exprList(argument("spanliteral", stringLiteral("1h")))) .build()); // Test span literal with decimal value and minute unit @@ -1634,9 +1616,7 @@ public void testVisitSpanLiteral() { intLiteral(2), SpanUnit.m))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(true)))) + .arguments(exprList(argument("spanliteral", stringLiteral("2m")))) .build()); // Test span literal without unit (should use NONE unit) @@ -1652,9 +1632,7 @@ public void testVisitSpanLiteral() { intLiteral(10), SpanUnit.NONE))) .aggregationFunction(alias("count()", aggregate("count", allFields()))) - .arguments( - exprList( - argument("limit", intLiteral(10)), argument("useother", booleanLiteral(true)))) + .arguments(exprList(argument("spanliteral", intLiteral(10)))) .build()); } diff --git a/ppl/src/test/java/org/opensearch/sql/ppl/utils/PPLQueryDataAnonymizerTest.java b/ppl/src/test/java/org/opensearch/sql/ppl/utils/PPLQueryDataAnonymizerTest.java index 1a15043998..848fcbd58a 100644 --- a/ppl/src/test/java/org/opensearch/sql/ppl/utils/PPLQueryDataAnonymizerTest.java +++ b/ppl/src/test/java/org/opensearch/sql/ppl/utils/PPLQueryDataAnonymizerTest.java @@ -255,8 +255,7 @@ public void testReverseCommand() { @Test public void testTimechartCommand() { assertEquals( - "source=table | timechart limit=*** useother=*** count() by span(identifier, *** m)" - + " identifier", + "source=table | timechart count() by span(identifier, *** m) identifier", anonymize("source=t | timechart count() by host")); }