Skip to content

Commit 49aee0d

Browse files
yuancuyuancu
authored
Specify timestamp field with timefield in timechart command (#4784) (#4863)
* Support param timefield to specify span field in timechart * Update doc to introduce timefield parameter * Update ASTBuilderTest for chart: default args are handled in rel node visitor * Fix ast expression builder test * Fix anomanyzer test * Support using specified timefield in per functions * Omit by-timestamp clause in timechart command * Mask timefield argument in anonymizer * Anonymize argument span --------- (cherry picked from commit afc98dd) Signed-off-by: Yuanchun Shen <yuanchu@amazon.com>
1 parent 399cace commit 49aee0d

13 files changed

Lines changed: 175 additions & 147 deletions

File tree

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

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -97,16 +97,14 @@ private UnresolvedPlan transformPerFunction() {
9797

9898
PerFunction perFunc = perFuncOpt.get();
9999
// For chart, the rowSplit should contain the span information
100-
UnresolvedExpression spanExpr = rowSplit;
101-
if (rowSplit instanceof Alias) {
102-
spanExpr = ((Alias) rowSplit).getDelegated();
103-
}
100+
UnresolvedExpression spanExpr =
101+
rowSplit instanceof Alias ? ((Alias) rowSplit).getDelegated() : rowSplit;
104102
if (!(spanExpr instanceof Span)) {
105103
return this; // Cannot transform without span information
106104
}
107105

108106
Span span = (Span) spanExpr;
109-
Field spanStartTime = AstDSL.implicitTimestampField();
107+
Field spanStartTime = (Field) span.getField();
110108
Function spanEndTime = timestampadd(span.getUnit(), span.getValue(), spanStartTime);
111109
Function spanMillis = timestampdiff(MILLISECOND, spanStartTime, spanEndTime);
112110
final int SECOND_IN_MILLISECOND = 1000;

‎docs/user/ppl/cmd/timechart.rst‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,14 @@ Syntax
2222

2323
.. code-block:: text
2424
25-
timechart [span=<time_interval>] [limit=<number>] [useother=<boolean>] <aggregation_function> [by <field>]
25+
timechart [timefield=<field_name>] [span=<time_interval>] [limit=<number>] [useother=<boolean>] <aggregation_function> [by <field>]
2626
2727
**Parameters:**
2828

29+
* **timefield**: optional. Specifies the timestamp field to use for time interval grouping. **Default**: ``@timestamp``.
30+
2931
* **span**: optional. Specifies the time interval for grouping data.
30-
32+
3133
* Default: 1m (1 minute)
3234
* Available time units:
3335

@@ -105,7 +107,7 @@ Return type: DOUBLE
105107
Notes
106108
=====
107109

108-
* The ``timechart`` command requires a timestamp field named ``@timestamp`` in the data.
110+
* 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.
109111
* Results are returned in an unpivoted format with separate rows for each time-field combination that has data.
110112
* Only combinations with actual data are included in the results - empty combinations are omitted rather than showing null or zero values.
111113
* 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‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
import org.json.JSONObject;
1414
import org.junit.jupiter.api.Test;
1515
import org.opensearch.client.ResponseException;
16+
import org.opensearch.sql.common.utils.StringUtils;
1617
import org.opensearch.sql.ppl.PPLIntegTestCase;
1718

1819
public class CalciteTimechartCommandIT extends PPLIntegTestCase {
@@ -64,7 +65,7 @@ public void testTimechartWithMinuteSpanAndGroupBy() throws IOException {
6465
}
6566

6667
@Test
67-
public void testTimechartWithoutTimestampField() throws IOException {
68+
public void testTimechartWithoutTimestampField() {
6869
Throwable exception =
6970
assertThrows(
7071
ResponseException.class,
@@ -74,6 +75,16 @@ public void testTimechartWithoutTimestampField() throws IOException {
7475
verifyErrorMessageContains(exception, "Field [@timestamp] not found.");
7576
}
7677

78+
@Test
79+
public void testTimechartWithCustomTimeField() throws IOException {
80+
JSONObject result =
81+
executeQuery(
82+
StringUtils.format(
83+
"source=%s | timechart timefield=birthdate span=1year count()", TEST_INDEX_BANK));
84+
verifySchema(result, schema("birthdate", "timestamp"), schema("count()", "bigint"));
85+
verifyDataRows(result, rows("2017-01-01 00:00:00", 2), rows("2018-01-01 00:00:00", 5));
86+
}
87+
7788
@Test
7889
public void testTimechartWithMinuteSpanNoGroupBy() throws IOException {
7990
JSONObject result = executeQuery("source=events | timechart span=1m avg(cpu_usage)");

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55

66
package org.opensearch.sql.calcite.remote;
77

8+
import static org.opensearch.sql.util.MatcherUtils.closeTo;
89
import static org.opensearch.sql.util.MatcherUtils.rows;
910
import static org.opensearch.sql.util.MatcherUtils.schema;
1011
import static org.opensearch.sql.util.MatcherUtils.verifyDataRows;
@@ -13,6 +14,8 @@
1314
import java.io.IOException;
1415
import org.json.JSONObject;
1516
import org.junit.jupiter.api.Test;
17+
import org.opensearch.sql.common.utils.StringUtils;
18+
import org.opensearch.sql.legacy.TestsConstants;
1619
import org.opensearch.sql.ppl.PPLIntegTestCase;
1720

1821
public class CalciteTimechartPerFunctionIT extends PPLIntegTestCase {
@@ -24,6 +27,7 @@ public void init() throws Exception {
2427
disallowCalciteFallback();
2528

2629
loadIndex(Index.EVENTS_TRAFFIC);
30+
loadIndex(Index.BANK);
2731
}
2832

2933
@Test
@@ -208,4 +212,26 @@ public void testTimechartPerDayWithByClause() throws IOException {
208212
rows("2025-09-08 10:02:00", "server1", 43200.0), // 60 * 720
209213
rows("2025-09-08 10:02:00", "server2", 129600.0)); // 180 * 720
210214
}
215+
216+
@Test
217+
public void testTimechartPerMonthWithSpecifiedSpan() throws IOException {
218+
JSONObject result =
219+
executeQuery(
220+
StringUtils.format(
221+
"source=%s | timechart timefield=birthdate span=1month per_day(balance) by gender",
222+
TestsConstants.TEST_INDEX_BANK));
223+
verifySchema(
224+
result,
225+
schema("birthdate", "timestamp"),
226+
schema("gender", "string"),
227+
schema("per_day(balance)", "double"));
228+
verifyDataRows(
229+
result,
230+
closeTo("2017-10-01 00:00:00", "M", 1265.3225806451612),
231+
closeTo("2017-11-01 00:00:00", "M", 189.53333333333333),
232+
closeTo("2018-06-01 00:00:00", "F", 1094.6),
233+
closeTo("2018-06-01 00:00:00", "M", 547.2666666666667),
234+
closeTo("2018-08-01 00:00:00", "F", 2858.9032258064517),
235+
closeTo("2018-11-01 00:00:00", "M", 139.33333333333334));
236+
}
211237
}

‎ppl/src/main/antlr/OpenSearchPPLLexer.g4‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,7 @@ LIMIT: 'LIMIT';
146146
USEOTHER: 'USEOTHER';
147147
OTHERSTR: 'OTHERSTR';
148148
NULLSTR: 'NULLSTR';
149+
TIMEFIELD: 'TIMEFIELD';
149150
INPUT: 'INPUT';
150151
OUTPUT: 'OUTPUT';
151152
PATH: 'PATH';

‎ppl/src/main/antlr/OpenSearchPPLParser.g4‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,7 @@ timechartParameter
332332
: LIMIT EQUAL integerLiteral
333333
| SPAN EQUAL spanLiteral
334334
| USEOTHER EQUAL (booleanLiteral | ident)
335+
| TIMEFIELD EQUAL (ident | stringLiteral)
335336
;
336337

337338
spanLiteral
@@ -1613,6 +1614,7 @@ searchableKeyWord
16131614
| SED
16141615
| MAX_MATCH
16151616
| OFFSET_FIELD
1617+
| TIMEFIELD
16161618
| patternMethod
16171619
| patternMode
16181620
// AGGREGATIONS AND WINDOW

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

Lines changed: 18 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,6 @@
6363
import org.opensearch.sql.ast.expression.SearchAnd;
6464
import org.opensearch.sql.ast.expression.SearchExpression;
6565
import org.opensearch.sql.ast.expression.SearchGroup;
66-
import org.opensearch.sql.ast.expression.Span;
67-
import org.opensearch.sql.ast.expression.SpanUnit;
6866
import org.opensearch.sql.ast.expression.UnresolvedArgument;
6967
import org.opensearch.sql.ast.expression.UnresolvedExpression;
7068
import org.opensearch.sql.ast.expression.WindowFrame;
@@ -772,42 +770,28 @@ private List<UnresolvedExpression> parseAggTerms(
772770
/** Timechart command. */
773771
@Override
774772
public UnresolvedPlan visitTimechartCommand(OpenSearchPPLParser.TimechartCommandContext ctx) {
775-
UnresolvedExpression binExpression =
776-
AstDSL.span(AstDSL.implicitTimestampField(), AstDSL.intLiteral(1), SpanUnit.m);
777-
Integer limit = 10;
778-
Boolean useOther = true;
779-
// Process timechart parameters
780-
for (OpenSearchPPLParser.TimechartParameterContext paramCtx : ctx.timechartParameter()) {
781-
UnresolvedExpression param = internalVisitExpression(paramCtx);
782-
if (param instanceof Span) {
783-
binExpression = param;
784-
} else if (param instanceof Literal) {
785-
Literal literal = (Literal) param;
786-
if (DataType.BOOLEAN.equals(literal.getType())) {
787-
useOther = (Boolean) literal.getValue();
788-
} else if (DataType.INTEGER.equals(literal.getType())
789-
|| DataType.LONG.equals(literal.getType())) {
790-
limit = (Integer) literal.getValue();
791-
}
792-
}
793-
}
773+
List<Argument> arguments = ArgumentFactory.getArgumentList(ctx, expressionBuilder);
774+
ArgumentMap argMap = ArgumentMap.of(arguments);
775+
Literal spanLiteral = argMap.getOrDefault("spanliteral", AstDSL.stringLiteral("1m"));
776+
String timeFieldName =
777+
Optional.ofNullable(argMap.get("timefield"))
778+
.map(l -> (String) l.getValue())
779+
.orElse(OpenSearchConstants.IMPLICIT_FIELD_TIMESTAMP);
780+
Field spanField = AstDSL.field(timeFieldName);
781+
Alias span =
782+
AstDSL.alias(timeFieldName, AstDSL.spanFromSpanLengthLiteral(spanField, spanLiteral));
794783
UnresolvedExpression aggregateFunction = parseAggTerms(List.of(ctx.statsAggTerm())).get(0);
795-
796784
UnresolvedExpression byField =
797-
ctx.fieldExpression() != null ? internalVisitExpression(ctx.fieldExpression()) : null;
798-
List<Argument> arguments =
799-
List.of(
800-
new Argument("limit", AstDSL.intLiteral(limit)),
801-
new Argument("useother", AstDSL.booleanLiteral(useOther)));
802-
binExpression = AstDSL.alias(OpenSearchConstants.IMPLICIT_FIELD_TIMESTAMP, binExpression);
803-
if (byField != null) {
804-
byField =
805-
AstDSL.alias(
806-
StringUtils.unquoteIdentifier(getTextInQuery(ctx.fieldExpression())), byField);
807-
}
785+
Optional.ofNullable(ctx.fieldExpression())
786+
.map(
787+
f ->
788+
AstDSL.alias(
789+
StringUtils.unquoteIdentifier(getTextInQuery(f)),
790+
internalVisitExpression(f)))
791+
.orElse(null);
808792
return Chart.builder()
809793
.aggregationFunction(aggregateFunction)
810-
.rowSplit(binExpression)
794+
.rowSplit(span)
811795
.columnSplit(byField)
812796
.arguments(arguments)
813797
.build();

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

Lines changed: 1 addition & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -749,7 +749,7 @@ public UnresolvedExpression visitMaxOption(OpenSearchPPLParser.MaxOptionContext
749749
return new Argument("max", (Literal) this.visit(ctx.integerLiteral()));
750750
}
751751

752-
private QualifiedName visitIdentifiers(List<? extends ParserRuleContext> ctx) {
752+
public QualifiedName visitIdentifiers(List<? extends ParserRuleContext> ctx) {
753753
return new QualifiedName(
754754
ctx.stream()
755755
.map(RuleContext::getText)
@@ -987,47 +987,6 @@ public UnresolvedExpression visitTimeModifierValue(
987987
return AstDSL.stringLiteral(osDateMathExpression);
988988
}
989989

990-
@Override
991-
public UnresolvedExpression visitTimechartParameter(
992-
OpenSearchPPLParser.TimechartParameterContext ctx) {
993-
UnresolvedExpression timechartParameter;
994-
if (ctx.SPAN() != null) {
995-
// Convert span=1h to span(@timestamp, 1h)
996-
Literal spanLiteral = (Literal) visit(ctx.spanLiteral());
997-
timechartParameter =
998-
AstDSL.spanFromSpanLengthLiteral(AstDSL.implicitTimestampField(), spanLiteral);
999-
} else if (ctx.LIMIT() != null) {
1000-
Literal limit = (Literal) visit(ctx.integerLiteral());
1001-
if ((Integer) limit.getValue() < 0) {
1002-
throw new IllegalArgumentException("Limit must be a non-negative number");
1003-
}
1004-
timechartParameter = limit;
1005-
} else if (ctx.USEOTHER() != null) {
1006-
UnresolvedExpression useOther;
1007-
if (ctx.booleanLiteral() != null) {
1008-
useOther = visit(ctx.booleanLiteral());
1009-
} else if (ctx.ident() != null) {
1010-
QualifiedName ident = visitIdentifiers(List.of(ctx.ident()));
1011-
String useOtherValue = ident.toString();
1012-
if ("true".equalsIgnoreCase(useOtherValue) || "t".equalsIgnoreCase(useOtherValue)) {
1013-
useOther = AstDSL.booleanLiteral(true);
1014-
} else if ("false".equalsIgnoreCase(useOtherValue) || "f".equalsIgnoreCase(useOtherValue)) {
1015-
useOther = AstDSL.booleanLiteral(false);
1016-
} else {
1017-
throw new IllegalArgumentException(
1018-
"Invalid useOther value: " + ctx.ident().getText() + ". Expected true/false or t/f");
1019-
}
1020-
} else {
1021-
throw new IllegalArgumentException("value for useOther must be a boolean or identifier");
1022-
}
1023-
timechartParameter = useOther;
1024-
} else {
1025-
throw new IllegalArgumentException(
1026-
String.format("A parameter of timechart must be a span, limit or useOther, got %s", ctx));
1027-
}
1028-
return timechartParameter;
1029-
}
1030-
1031990
/**
1032991
* Process time range expressions (EARLIEST='value' or LATEST='value') It creates a Comparison
1033992
* filter like @timestamp >= timeModifierValue

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
import org.opensearch.sql.ppl.antlr.parser.OpenSearchPPLParser.SortFieldContext;
3434
import org.opensearch.sql.ppl.antlr.parser.OpenSearchPPLParser.StreamstatsCommandContext;
3535
import org.opensearch.sql.ppl.antlr.parser.OpenSearchPPLParser.SuffixSortFieldContext;
36+
import org.opensearch.sql.ppl.parser.AstExpressionBuilder;
3637

3738
/** Util class to get all arguments as a list from the PPL command. */
3839
public class ArgumentFactory {
@@ -249,6 +250,60 @@ public static List<Argument> getArgumentList(ChartCommandContext ctx) {
249250
return arguments;
250251
}
251252

253+
public static List<Argument> getArgumentList(
254+
OpenSearchPPLParser.TimechartCommandContext timechartCtx,
255+
AstExpressionBuilder expressionBuilder) {
256+
List<Argument> arguments = new ArrayList<>();
257+
for (OpenSearchPPLParser.TimechartParameterContext ctx : timechartCtx.timechartParameter()) {
258+
if (ctx.SPAN() != null) {
259+
arguments.add(
260+
new Argument("spanliteral", (Literal) expressionBuilder.visit(ctx.spanLiteral())));
261+
} else if (ctx.LIMIT() != null) {
262+
Literal limit = getArgumentValue(ctx.integerLiteral());
263+
if ((Integer) limit.getValue() < 0) {
264+
throw new IllegalArgumentException("Limit must be a non-negative number");
265+
}
266+
arguments.add(new Argument("limit", limit));
267+
} else if (ctx.USEOTHER() != null) {
268+
Literal useOther;
269+
if (ctx.booleanLiteral() != null) {
270+
useOther = getArgumentValue(ctx.booleanLiteral());
271+
} else if (ctx.ident() != null) {
272+
String identLiteral = expressionBuilder.visitIdentifiers(List.of(ctx.ident())).toString();
273+
if ("true".equalsIgnoreCase(identLiteral) || "t".equalsIgnoreCase(identLiteral)) {
274+
useOther = AstDSL.booleanLiteral(true);
275+
} else if ("false".equalsIgnoreCase(identLiteral) || "f".equalsIgnoreCase(identLiteral)) {
276+
useOther = AstDSL.booleanLiteral(false);
277+
} else {
278+
throw new IllegalArgumentException(
279+
"Invalid useOther value: "
280+
+ ctx.ident().getText()
281+
+ ". Expected true/false or t/f");
282+
}
283+
} else {
284+
throw new IllegalArgumentException("value for useOther must be a boolean or identifier");
285+
}
286+
arguments.add(new Argument("useother", useOther));
287+
} else if (ctx.TIMEFIELD() != null) {
288+
Literal timeField;
289+
if (ctx.ident() != null) {
290+
timeField =
291+
AstDSL.stringLiteral(
292+
expressionBuilder.visitIdentifiers(List.of(ctx.ident())).toString());
293+
} else {
294+
timeField = getArgumentValue(ctx.stringLiteral());
295+
}
296+
arguments.add(new Argument("timefield", timeField));
297+
} else {
298+
throw new IllegalArgumentException(
299+
String.format(
300+
"A parameter of timechart must be a span, limit, useother, or timefield, got %s",
301+
ctx));
302+
}
303+
}
304+
return arguments;
305+
}
306+
252307
/**
253308
* Get list of {@link Argument}.
254309
*

0 commit comments

Comments
 (0)