From 9c390fd2018480d48a3f7b07f7e6da9cd8dbb20e Mon Sep 17 00:00:00 2001 From: Artem Fetishev <149964189+rtm0@users.noreply.github.com> Date: Tue, 5 Nov 2024 15:36:14 +0100 Subject: [PATCH] documentation: Fix query docs This commit changes the following: - The datetime has been fixed so it corresponds to the timestamps in example samples. The datetime now also include the UTC time zone and is changed to adhere ISO format. - The data points in query range result have been fixed to match the inserted data. Signed-off-by: Artem Fetishev (cherry picked from commit d311c12dcef40ef6cff39672f0c5554db4f92e31) --- docs/keyConcepts/keyConcepts.md | 108 ++++++++++++++++---------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/keyConcepts/keyConcepts.md b/docs/keyConcepts/keyConcepts.md index 7084a3c82..5aac4a0b2 100644 --- a/docs/keyConcepts/keyConcepts.md +++ b/docs/keyConcepts/keyConcepts.md @@ -497,19 +497,19 @@ where `timestamp` equals to the `time` query arg, while the `value` contains `qu To understand how instant queries work, let's begin with a data sample: ``` -foo_bar 1.00 1652169600000 # 2022-05-10 10:00:00 -foo_bar 2.00 1652169660000 # 2022-05-10 10:01:00 -foo_bar 3.00 1652169720000 # 2022-05-10 10:02:00 -foo_bar 5.00 1652169840000 # 2022-05-10 10:04:00, one point missed -foo_bar 5.50 1652169960000 # 2022-05-10 10:06:00, one point missed -foo_bar 5.50 1652170020000 # 2022-05-10 10:07:00 -foo_bar 4.00 1652170080000 # 2022-05-10 10:08:00 -foo_bar 3.50 1652170260000 # 2022-05-10 10:11:00, two points missed -foo_bar 3.25 1652170320000 # 2022-05-10 10:12:00 -foo_bar 3.00 1652170380000 # 2022-05-10 10:13:00 -foo_bar 2.00 1652170440000 # 2022-05-10 10:14:00 -foo_bar 1.00 1652170500000 # 2022-05-10 10:15:00 -foo_bar 4.00 1652170560000 # 2022-05-10 10:16:00 +foo_bar 1.00 1652169600000 # 2022-05-10T08:00:00Z +foo_bar 2.00 1652169660000 # 2022-05-10T08:01:00Z +foo_bar 3.00 1652169720000 # 2022-05-10T08:02:00Z +foo_bar 5.00 1652169840000 # 2022-05-10T08:04:00Z, one point missed +foo_bar 5.50 1652169960000 # 2022-05-10T08:06:00Z, one point missed +foo_bar 5.50 1652170020000 # 2022-05-10T08:07:00Z +foo_bar 4.00 1652170080000 # 2022-05-10T08:08:00Z +foo_bar 3.50 1652170260000 # 2022-05-10T08:11:00Z, two points missed +foo_bar 3.25 1652170320000 # 2022-05-10T08:12:00Z +foo_bar 3.00 1652170380000 # 2022-05-10T08:13:00Z +foo_bar 2.00 1652170440000 # 2022-05-10T08:14:00Z +foo_bar 1.00 1652170500000 # 2022-05-10T08:15:00Z +foo_bar 4.00 1652170560000 # 2022-05-10T08:16:00Z ``` The data above contains a list of samples for the `foo_bar` time series with time intervals between samples @@ -518,11 +518,11 @@ ranging from 1m to 3m. If we plot this data sample on the graph, it will have th ![data samples](data_samples.webp) {width="500"} -To get the value of the `foo_bar` series at some specific moment of time, for example `2022-05-10 10:03:00`, in +To get the value of the `foo_bar` series at some specific moment of time, for example `2022-05-10T08:03:00Z`, in VictoriaMetrics we need to issue an **instant query**: ```sh -curl "http:///api/v1/query?query=foo_bar&time=2022-05-10T10:03:00.000Z" +curl "http:///api/v1/query?query=foo_bar&time=2022-05-10T08:03:00.000Z" ``` ```json @@ -536,7 +536,7 @@ curl "http:///api/v1/query?query=foo_bar&time=2022-05-10T "__name__": "foo_bar" }, "value": [ - 1652169780, // 2022-05-10 10:03:00 + 1652169780, // 2022-05-10T08:03:00Z "3" ] } @@ -546,8 +546,8 @@ curl "http:///api/v1/query?query=foo_bar&time=2022-05-10T ``` In response, VictoriaMetrics returns a single sample-timestamp pair with a value of `3` for the series -`foo_bar` at the given moment in time `2022-05-10 10:03`. But, if we take a look at the original data sample again, -we'll see that there is no raw sample at `2022-05-10 10:03`. When there is no raw sample at the +`foo_bar` at the given moment in time `2022-05-10T08:03:00Z`. But, if we take a look at the original data sample again, +we'll see that there is no raw sample at `2022-05-10T08:03:00Z`. When there is no raw sample at the requested timestamp, VictoriaMetrics will try to locate the closest sample before the requested timestamp: ![instant query](instant_query.webp) @@ -592,11 +592,11 @@ matching the filter in `query` expression. Each returned series contains `(times at `start`, `start+step`, `start+2*step`, ..., `end` timestamps. In other words, Range query is an [Instant query](#instant-query) executed independently at `start`, `start+step`, ..., `end` timestamps. -For example, to get the values of `foo_bar` during the time range from `2022-05-10 09:59:00` to `2022-05-10 10:17:00`, +For example, to get the values of `foo_bar` during the time range from `2022-05-10T07:59:00Z` to `2022-05-10T08:17:00Z`, we need to issue a range query: ```sh -curl "http:///api/v1/query_range?query=foo_bar&step=1m&start=2022-05-10T09:59:00.000Z&end=2022-05-10T10:17:00.000Z" +curl "http:///api/v1/query_range?query=foo_bar&step=1m&start=2022-05-10T07:59:00.000Z&end=2022-05-10T08:17:00.000Z" ``` ```json @@ -628,44 +628,44 @@ curl "http:///api/v1/query_range?query=foo_bar&step=1m&st ], [ 1652169840, - "7" - ], - [ - 1652169900, - "7" - ], - [ - 1652169960, - "7.5" - ], - [ - 1652170020, - "7.5" - ], - [ - 1652170080, - "6" - ], - [ - 1652170140, - "6" - ], - [ - 1652170260, - "5.5" - ], - [ - 1652170320, - "5.25" - ], - [ - 1652170380, "5" ], [ - 1652170440, + 1652169900, + "5" + ], + [ + 1652169960, + "5.5" + ], + [ + 1652170020, + "5.5" + ], + [ + 1652170080, + "4" + ], + [ + 1652170140, + "4" + ], + [ + 1652170260, + "3.5" + ], + [ + 1652170320, + "3.25" + ], + [ + 1652170380, "3" ], + [ + 1652170440, + "2" + ], [ 1652170500, "1" @@ -686,7 +686,7 @@ curl "http:///api/v1/query_range?query=foo_bar&step=1m&st ``` In response, VictoriaMetrics returns `17` sample-timestamp pairs for the series `foo_bar` at the given time range -from `2022-05-10 09:59:00` to `2022-05-10 10:17:00`. But, if we take a look at the original data sample again, we'll +from `2022-05-10T07:59:00Z` to `2022-05-10T08:17:00Z`. But, if we take a look at the original data sample again, we'll see that it contains only 13 raw samples. What happens here is that the range query is actually an [instant query](#instant-query) executed `1 + (start-end)/step` times on the time range from `start` to `end`. If we plot this request in VictoriaMetrics the graph will be shown as the following: