upstream/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2026-05-28 04:02:21 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

promql: rename min/max duration expr functions to least/greatest

Browse source 
Rename the `min()` and `max()` duration expression functions to
`least()` and `greatest()` to avoid conflicts with the existing
PromQL aggregate functions `min` and `max`.

Update documentation and tests accordingly.

Signed-off-by: Julien Pivotto <291750+roidelapluie@users.noreply.github.com>
This commit is contained in:
Julien Pivotto 2026-05-13 17:35:52 +02:00
parent e793b26713
commit 76c859969d
11 changed files with 638 additions and 613 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/feature_flags.md
View file

@ -223,7 +223,10 @@ For a **range query**, it resolves to the full range of the query (end time - st
For an **instant query**, it resolves to `0s`.
This is particularly useful in combination with `@end()` to look back over the entire query range, e.g., `max_over_time(metric[range()] @ end())`.
`min(<duration>, <duration>)` and `max(<duration>, <duration>)` can be used to find the minimum or maximum of two duration expressions.
`least(<duration>, <duration>)` and `greatest(<duration>, <duration>)` select between two duration expressions.
`least` returns the smaller of the two, which is useful for capping a duration at a maximum value.
`greatest` returns the larger of the two, which is useful for enforcing a minimum value.
For example, `greatest(step(), 5s)` ensures the duration is never shorter than `5s`, while `least(range(), 1h)` caps the duration at `1h`.
**Note**: Duration expressions are not supported in the @ timestamp operator.
@ -245,8 +248,8 @@ Examples of equivalent durations:
* `4h % 3h` is equivalent to `1h` or `3600s`
* `(2 ^ 3) * 1m` is equivalent to `8m` or `480s`
* `step() + 1` is equivalent to the query step width increased by 1s.
* `max(step(), 5s)` is equivalent to the larger of the query step width and `5s`.
* `min(2 * step() + 5s, 5m)` is equivalent to the smaller of twice the query step increased by `5s` and `5m`.
* `greatest(step(), 5s)` is equivalent to the larger of the query step width and `5s`.
* `least(2 * step() + 5s, 5m)` is equivalent to the smaller of twice the query step increased by `5s` and `5m`.
## OTLP Native Delta Support

4
promql/durations.go
View file

@ -135,9 +135,9 @@ func (v *durationVisitor) evaluateDurationExpr(expr parser.Expr) (float64, error
return float64(v.step.Seconds()), nil
case parser.RANGE:
return float64(v.queryRange.Seconds()), nil
case parser.MIN:
case parser.LEAST:
return math.Min(lhs, rhs), nil
case parser.MAX:
case parser.GREATEST:
return math.Max(lhs, rhs), nil
case parser.ADD:
if n.LHS == nil {

4
promql/durations_test.go
View file

@ -228,7 +228,7 @@ func TestCalculateDuration(t *testing.T) {
expected: 150 * time.Second,
},
{
name: "max of step and range",
name: "greatest of step and range",
expr: &parser.DurationExpr{
LHS: &parser.DurationExpr{
Op: parser.STEP,
@ -236,7 +236,7 @@ func TestCalculateDuration(t *testing.T) {
RHS: &parser.DurationExpr{
Op: parser.RANGE,
},
Op: parser.MAX,
Op: parser.GREATEST,
},
expected: 5 * time.Minute,
},

16
promql/parser/generated_parser.y
View file

@ -159,6 +159,8 @@ START
END
STEP
RANGE
GREATEST
LEAST
%token preprocessorEnd
// Counter reset hints.
@ -183,7 +185,7 @@ START_METRIC_SELECTOR
// Type definitions for grammar rules.
%type <matchers> label_match_list
%type <matcher> label_matcher
%type <item> aggregate_op grouping_label match_op maybe_label metric_identifier unary_op at_modifier_preprocessors string_identifier counter_reset_hint min_max
%type <item> aggregate_op grouping_label match_op maybe_label metric_identifier unary_op at_modifier_preprocessors string_identifier counter_reset_hint greatest_least
%type <labels> label_set metric
%type <lblList> label_set_list
%type <label> label_set_item
@ -814,7 +816,7 @@ metric : metric_identifier label_set
;
metric_identifier: AVG | BOTTOMK | BY | COUNT | COUNT_VALUES | FILL | FILL_LEFT | FILL_RIGHT | GROUP | IDENTIFIER | LAND | LOR | LUNLESS | MAX | METRIC_IDENTIFIER | MIN | OFFSET | QUANTILE | STDDEV | STDVAR | SUM | TOPK | WITHOUT | START | END | LIMITK | LIMIT_RATIO | STEP | RANGE | ANCHORED | SMOOTHED;
metric_identifier: AVG | BOTTOMK | BY | COUNT | COUNT_VALUES | FILL | FILL_LEFT | FILL_RIGHT | GROUP | IDENTIFIER | LAND | LOR | LUNLESS | MAX | METRIC_IDENTIFIER | MIN | OFFSET | QUANTILE | STDDEV | STDVAR | SUM | TOPK | WITHOUT | START | END | LIMITK | LIMIT_RATIO | STEP | RANGE | ANCHORED | SMOOTHED | GREATEST | LEAST;
label_set : LEFT_BRACE label_set_list RIGHT_BRACE
{ $$ = labels.New($2...) }
@ -1072,7 +1074,7 @@ counter_reset_hint : UNKNOWN_COUNTER_RESET | COUNTER_RESET | NOT_COUNTER_RESET |
aggregate_op : AVG | BOTTOMK | COUNT | COUNT_VALUES | GROUP | MAX | MIN | QUANTILE | STDDEV | STDVAR | SUM | TOPK | LIMITK | LIMIT_RATIO;
// Inside of grouping options label names can be recognized as keywords by the lexer. This is a list of keywords that could also be a label name.
maybe_label : AVG | BOOL | BOTTOMK | BY | COUNT | COUNT_VALUES | GROUP | GROUP_LEFT | GROUP_RIGHT | FILL | FILL_LEFT | FILL_RIGHT | IDENTIFIER | IGNORING | LAND | LOR | LUNLESS | MAX | METRIC_IDENTIFIER | MIN | OFFSET | ON | QUANTILE | STDDEV | STDVAR | SUM | TOPK | START | END | ATAN2 | LIMITK | LIMIT_RATIO | STEP | RANGE | ANCHORED | SMOOTHED;
maybe_label : AVG | BOOL | BOTTOMK | BY | COUNT | COUNT_VALUES | GROUP | GROUP_LEFT | GROUP_RIGHT | FILL | FILL_LEFT | FILL_RIGHT | IDENTIFIER | IGNORING | LAND | LOR | LUNLESS | MAX | METRIC_IDENTIFIER | MIN | OFFSET | ON | QUANTILE | STDDEV | STDVAR | SUM | TOPK | START | END | ATAN2 | LIMITK | LIMIT_RATIO | STEP | RANGE | ANCHORED | SMOOTHED | GREATEST | LEAST;
unary_op : ADD | SUB;
@ -1247,7 +1249,7 @@ offset_duration_expr : number_duration_literal
yylex.(*parser).experimentalDurationExpr(de)
$$ = de
}
| min_max LEFT_PAREN duration_expr COMMA duration_expr RIGHT_PAREN
| greatest_least LEFT_PAREN duration_expr COMMA duration_expr RIGHT_PAREN
{
de := &DurationExpr{
Op: $1.Typ,
@ -1259,7 +1261,7 @@ offset_duration_expr : number_duration_literal
yylex.(*parser).experimentalDurationExpr(de)
$$ = de
}
| unary_op min_max LEFT_PAREN duration_expr COMMA duration_expr RIGHT_PAREN
| unary_op greatest_least LEFT_PAREN duration_expr COMMA duration_expr RIGHT_PAREN
{
de := &DurationExpr{
Op: $1.Typ,
@ -1293,7 +1295,7 @@ offset_duration_expr : number_duration_literal
| duration_expr
;
min_max: MIN | MAX ;
greatest_least: GREATEST | LEAST ;
duration_expr : number_duration_literal
{
@ -1397,7 +1399,7 @@ duration_expr : number_duration_literal
yylex.(*parser).experimentalDurationExpr(de)
$$ = de
}
| min_max LEFT_PAREN duration_expr COMMA duration_expr RIGHT_PAREN
| greatest_least LEFT_PAREN duration_expr COMMA duration_expr RIGHT_PAREN
{
de := &DurationExpr{
Op: $1.Typ,

1072
promql/parser/generated_parser.y.go
View file

File diff suppressed because it is too large Load diff

18
promql/parser/lex.go
View file

@ -143,10 +143,12 @@ var key = map[string]ItemType{
"bool": BOOL,
// Preprocessors.
"start": START,
"end": END,
"step": STEP,
"range": RANGE,
"start": START,
"end": END,
"step": STEP,
"range": RANGE,
"greatest": GREATEST,
"least": LEAST,
}
var histogramDesc = map[string]ItemType{
@ -937,10 +939,10 @@ func lexNumber(l *Lexer) stateFn {
// durationKeywordTokens maps lowercase duration keyword names to their token types.
var durationKeywordTokens = map[string]ItemType{
"step": STEP,
"range": RANGE,
"min": MIN,
"max": MAX,
"step": STEP,
"range": RANGE,
"greatest": GREATEST,
"least": LEAST,
}
// durationKeywordStartChars is the set of lowercase runes that can start a duration keyword,

60
promql/parser/parse_test.go
View file

@ -4610,7 +4610,7 @@ var testExpr = []struct {
},
},
{
input: `foo[max(step(),5s)]`,
input: `foo[greatest(step(),5s)]`,
expected: &MatrixSelector{
VectorSelector: &VectorSelector{
Name: "foo",
@ -4620,83 +4620,83 @@ var testExpr = []struct {
PosRange: posrange.PositionRange{Start: 0, End: 3},
},
RangeExpr: &DurationExpr{
Op: MAX,
Op: GREATEST,
LHS: &DurationExpr{
Op: STEP,
StartPos: 8,
EndPos: 14,
StartPos: 13,
EndPos: 19,
},
RHS: &NumberLiteral{
Val: 5,
Duration: true,
PosRange: posrange.PositionRange{Start: 15, End: 17},
PosRange: posrange.PositionRange{Start: 20, End: 22},
},
StartPos: 4,
EndPos: 18,
EndPos: 23,
},
EndPos: 19,
EndPos: 24,
},
},
{
input: `foo offset max(step(),5s)`,
input: `foo offset greatest(step(),5s)`,
expected: &VectorSelector{
Name: "foo",
LabelMatchers: []*labels.Matcher{
MustLabelMatcher(labels.MatchEqual, model.MetricNameLabel, "foo"),
},
PosRange: posrange.PositionRange{Start: 0, End: 25},
PosRange: posrange.PositionRange{Start: 0, End: 30},
OriginalOffsetExpr: &DurationExpr{
Op: MAX,
Op: GREATEST,
LHS: &DurationExpr{
Op: STEP,
StartPos: 15,
EndPos: 21,
StartPos: 20,
EndPos: 26,
},
RHS: &NumberLiteral{
Val: 5,
Duration: true,
PosRange: posrange.PositionRange{Start: 22, End: 24},
PosRange: posrange.PositionRange{Start: 27, End: 29},
},
StartPos: 11,
EndPos: 25,
EndPos: 30,
},
},
},
{
input: `foo offset -min(5s,step()+8s)`,
input: `foo offset -least(5s,step()+8s)`,
expected: &VectorSelector{
Name: "foo",
LabelMatchers: []*labels.Matcher{
MustLabelMatcher(labels.MatchEqual, model.MetricNameLabel, "foo"),
},
PosRange: posrange.PositionRange{Start: 0, End: 29},
PosRange: posrange.PositionRange{Start: 0, End: 31},
OriginalOffsetExpr: &DurationExpr{
Op: SUB,
RHS: &DurationExpr{
Op: MIN,
Op: LEAST,
LHS: &NumberLiteral{
Val: 5,
Duration: true,
PosRange: posrange.PositionRange{Start: 16, End: 18},
PosRange: posrange.PositionRange{Start: 18, End: 20},
},
RHS: &DurationExpr{
Op: ADD,
LHS: &DurationExpr{
Op: STEP,
StartPos: 19,
EndPos: 25,
StartPos: 21,
EndPos: 27,
},
RHS: &NumberLiteral{
Val: 8,
Duration: true,
PosRange: posrange.PositionRange{Start: 26, End: 28},
PosRange: posrange.PositionRange{Start: 28, End: 30},
},
},
StartPos: 12,
EndPos: 28,
EndPos: 30,
},
StartPos: 11,
EndPos: 28,
EndPos: 30,
},
},
},
@ -4793,7 +4793,7 @@ var testExpr = []struct {
},
},
{
input: `foo[max(range(),5s)]`,
input: `foo[greatest(range(),5s)]`,
expected: &MatrixSelector{
VectorSelector: &VectorSelector{
Name: "foo",
@ -4803,21 +4803,21 @@ var testExpr = []struct {
PosRange: posrange.PositionRange{Start: 0, End: 3},
},
RangeExpr: &DurationExpr{
Op: MAX,
Op: GREATEST,
LHS: &DurationExpr{
Op: RANGE,
StartPos: 8,
EndPos: 15,
StartPos: 13,
EndPos: 20,
},
RHS: &NumberLiteral{
Val: 5,
Duration: true,
PosRange: posrange.PositionRange{Start: 16, End: 18},
PosRange: posrange.PositionRange{Start: 21, End: 23},
},
StartPos: 4,
EndPos: 19,
EndPos: 24,
},
EndPos: 20,
EndPos: 25,
},
},
{

8
promql/parser/printer.go
View file

@ -205,14 +205,14 @@ func (node *DurationExpr) writeTo(b *bytes.Buffer) {
b.WriteString("step()")
case node.Op == RANGE:
b.WriteString("range()")
case node.Op == MIN:
b.WriteString("min(")
case node.Op == LEAST:
b.WriteString("least(")
b.WriteString(node.LHS.String())
b.WriteString(", ")
b.WriteString(node.RHS.String())
b.WriteByte(')')
case node.Op == MAX:
b.WriteString("max(")
case node.Op == GREATEST:
b.WriteString("greatest(")
b.WriteString(node.LHS.String())
b.WriteString(", ")
b.WriteString(node.RHS.String())

18
promql/parser/printer_test.go
View file

@ -270,22 +270,22 @@ func TestExprString(t *testing.T) {
out: "foo offset (5 * 2)",
},
{
in: "foo offset +min(10s, 20s)",
out: "foo offset min(10s, 20s)",
in: "foo offset +least(10s, 20s)",
out: "foo offset least(10s, 20s)",
},
{
in: "foo offset -min(10s, 20s)",
in: "foo offset -least(10s, 20s)",
},
{
in: "foo offset -min(10s, +max(step() ^ 2, 2))",
out: "foo offset -min(10s, max(step() ^ 2, 2))",
in: "foo offset -least(10s, +greatest(step() ^ 2, 2))",
out: "foo offset -least(10s, greatest(step() ^ 2, 2))",
},
{
in: "foo[200-min(-step()^+step(),1)]",
out: "foo[200 - min(-step() ^ step(), 1)]",
in: "foo[200-least(-step()^+step(),1)]",
out: "foo[200 - least(-step() ^ step(), 1)]",
},
{
in: "foo[200 - min(step() + 10s, -max(step() ^ 2, 3))]",
in: "foo[200 - least(step() + 10s, -greatest(step() ^ 2, 3))]",
},
{
in: "foo[range()]",
@ -300,7 +300,7 @@ func TestExprString(t *testing.T) {
in: "foo offset -range()",
},
{
in: "foo[max(range(), 5s)]",
in: "foo[greatest(range(), 5s)]",
},
{
in: `predict_linear(foo[1h], 3000)`,

26
promql/promqltest/testdata/duration_expression.test vendored
View file

@ -167,13 +167,13 @@ eval range from 50s to 60s step 10s count_over_time(metric1_total[1+(STep()-5)*2
eval range from 50s to 60s step 5s count_over_time(metric1_total[step()+1])
{} 6 6 6
eval range from 50s to 60s step 5s count_over_time(metric1_total[min(step()+1,1h)])
eval range from 50s to 60s step 5s count_over_time(metric1_total[least(step()+1,1h)])
{} 6 6 6
eval range from 50s to 60s step 5s count_over_time(metric1_total[max(min(step()+1,1h),1ms)])
eval range from 50s to 60s step 5s count_over_time(metric1_total[greatest(least(step()+1,1h),1ms)])
{} 6 6 6
eval range from 50s to 60s step 5s count_over_time(metric1_total[((max(min((step()+1),((1h))),1ms)))])
eval range from 50s to 60s step 5s count_over_time(metric1_total[((greatest(least((step()+1),((1h))),1ms)))])
{} 6 6 6
eval range from 50s to 60s step 5s metric1_total offset STEP()
@ -200,31 +200,31 @@ eval range from 50s to 60s step 5s metric1_total offset (STEP()/10)
eval range from 50s to 60s step 5s metric1_total offset (step())
metric1_total{} 45 50 55
eval range from 50s to 60s step 5s metric1_total offset min(step(), 1s)
eval range from 50s to 60s step 5s metric1_total offset least(step(), 1s)
metric1_total{} 49 54 59
eval range from 50s to 60s step 5s metric1_total offset min(step(), 1s)+8000
eval range from 50s to 60s step 5s metric1_total offset least(step(), 1s)+8000
{} 8049 8054 8059
eval range from 50s to 60s step 5s metric1_total offset -min(step(), 1s)+8000
eval range from 50s to 60s step 5s metric1_total offset -least(step(), 1s)+8000
{} 8051 8056 8061
eval range from 50s to 60s step 5s metric1_total offset -(min(step(), 1s))+8000
eval range from 50s to 60s step 5s metric1_total offset -(least(step(), 1s))+8000
{} 8051 8056 8061
eval range from 50s to 60s step 5s metric1_total offset -min(step(), 1s)^0
eval range from 50s to 60s step 5s metric1_total offset -least(step(), 1s)^0
{} 1 1 1
eval range from 50s to 60s step 5s metric1_total offset +min(step(), 1s)^0
eval range from 50s to 60s step 5s metric1_total offset +least(step(), 1s)^0
{} 1 1 1
eval range from 50s to 60s step 5s metric1_total offset min(step(), 1s)^0
eval range from 50s to 60s step 5s metric1_total offset least(step(), 1s)^0
{} 1 1 1
eval range from 50s to 60s step 5s metric1_total offset max(3s,min(step(), 1s))+8000
eval range from 50s to 60s step 5s metric1_total offset greatest(3s,least(step(), 1s))+8000
{} 8047 8052 8057
eval range from 50s to 60s step 5s metric1_total offset -(min(step(), 2s)-5)+8000
eval range from 50s to 60s step 5s metric1_total offset -(least(step(), 2s)-5)+8000
{} 8047 8052 8057
# Test range() function - resolves to query range (end - start).
@ -238,7 +238,7 @@ eval range from 50s to 60s step 5s count_over_time(metric1_total[range()])
eval range from 50s to 60s step 5s metric1_total offset range()
metric1_total{} 40 45 50
eval range from 50s to 60s step 5s metric1_total offset min(range(), 8s)
eval range from 50s to 60s step 5s metric1_total offset least(range(), 8s)
metric1_total{} 42 47 52
clear

16
web/api/v1/translate_ast_test.go
View file

@ -75,11 +75,11 @@ func TestTranslateASTDurationExpressions(t *testing.T) {
},
{
name: "complex matrix selector range expression",
query: `foo[max(step(),5m+3m) ]`,
query: `foo[greatest(step(),5m+3m) ]`,
wantType: "matrixSelector",
wantFields: map[string]any{
"range": int64(0),
"rangeExpr": durationExpr("max",
"rangeExpr": durationExpr("greatest",
durationExpr("step", nil, nil, false),
durationExpr("+", durationNumber("300", true), durationNumber("180", true), false),
false,
@ -87,13 +87,13 @@ func TestTranslateASTDurationExpressions(t *testing.T) {
},
},
{
name: "nested min and max matrix selector range expression",
query: `foo[min(max(step(),5m+3m),10m-2m)]`,
name: "nested least and greatest matrix selector range expression",
query: `foo[least(greatest(step(),5m+3m),10m-2m)]`,
wantType: "matrixSelector",
wantFields: map[string]any{
"range": int64(0),
"rangeExpr": durationExpr("min",
durationExpr("max",
"rangeExpr": durationExpr("least",
durationExpr("greatest",
durationExpr("step", nil, nil, false),
durationExpr("+", durationNumber("300", true), durationNumber("180", true), false),
false,
@ -149,12 +149,12 @@ func TestTranslateASTDurationExpressions(t *testing.T) {
},
{
name: "vector selector offset expression",
query: `foo offset -min(5s,step()+8s)`,
query: `foo offset -least(5s,step()+8s)`,
wantType: "vectorSelector",
wantFields: map[string]any{
"offset": int64(0),
"offsetExpr": durationExpr("-", nil,
durationExpr("min",
durationExpr("least",
durationNumber("5", true),
durationExpr("+", durationExpr("step", nil, nil, false), durationNumber("8", true), false),
false,