Skip to content

Commit fadd275

Browse files
docs: document forward offsets in the spec (#127)
#121 lets offset read later data with +<duration> or an unsigned duration. Update the spec's Offset section: examples for all three forms, the forward worked example, and the PromQL sign note (an unsigned offset now means the opposite of PromQL's). Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 3ce7ab9 commit fadd275

1 file changed

Lines changed: 12 additions & 5 deletions

File tree

‎spec.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -49,20 +49,27 @@ For example:
4949

5050
## Offset
5151

52-
`offset` reads the source from an earlier time. The query keeps its time range: each value is read from that far back and
53-
returned at the matching time in the query range. This makes it possible to compare a metric with its own past, for
52+
`offset` reads the source from another time. The query keeps its time range: each value is read from that far away
53+
and returned at the matching time in the query range. This makes it possible to compare a metric with its own past, for
5454
example this week with the same time last week:
5555

5656
```mpl
5757
// read the values from one hour earlier
5858
| offset -1h
59+
60+
// read the values from one hour later
61+
| offset +1h
62+
63+
// same as +1h
64+
| offset 1h
5965
```
6066

6167
With `offset -1h` and a time range of 10:00 to 11:00, the source reads 09:00 to 10:00, and the value recorded at 09:15
62-
is returned at 10:15.
68+
is returned at 10:15. With `offset +1h`, the source reads 11:00 to 12:00, and the value recorded at 11:15 is returned
69+
at 10:15.
6370

64-
- The duration uses the [relative time](#time-range) units and must start with `-`. A negative offset moves back in
65-
time, which is the opposite sign of PromQL's `offset`. Moving forward in time is not supported yet.
71+
- The duration uses the [relative time](#time-range) units. The sign matches the direction: `-` reads earlier, and `+`
72+
or no sign reads later. This is the opposite of PromQL, where `offset 1h` reads an hour earlier.
6673
- The offset operator is only valid right after the source, before `sample`, and at most once per source.
6774
- Each source in a [computation](#computation) has its own offset; a source without one reads the query's time range.
6875
`offset` cannot follow `compute`.

0 commit comments

Comments
 (0)