[docs] improve the documentation of query_range's interval param

[gabor]

the current documentation at https://grafana.com/docs/loki/latest/api/#query-loki-over-a-range-of-time says:

" Determines the sort order of logs. Supported values are forward or backward. Defaults to backward. "

i think it does not just control the sort order of the returned logs, it also controls where in time Loki begins to find log lines. if you go direction=backward, then the returned logs will start from the end timestamp, going in the direction of the start timestamp. and direction=forward does the opposite, the logs will start from the start timestamp, going in the direction of the end timestamp.

with an example: imagine i have a time-range that contains 6 log-lines, in timestamp-number-is-increasing order:

line1
line2
line3
line4
line5
line6

• if i say limit=2&direction=forward, i get line1 and line2
• if i say limit=2&direction=backward, i get line6 and line5

i think the documentation for the direction param should be improved to also describe this, because right now it may be interpreted as "it always returns the same log-lines, except in a different order"

[gabor]

(this is all just by me testing things, i am not 100% sure it works like this, but it really looks it works like this 😄 )

[JStickler]

@gabor, I think this line in the docs describes what you're talking about in this issue?

"The items in the values array are sorted by timestamp. The most recent item is first when using direction=backward. The oldest item is first when using direction=forward."

It appears below the code samples, so you may have missed it. Maybe we should move it up, just below the bulleted list of query parameters?

[gabor]

hi @JStickler ... i see your point, but when i read it, to me it sounds like it only describes the format of the output (the items in the values array..... in other words, to me it sounds like changing direction will change the way the results are ordered, but it will not affects which log-lines are in the result.

so i do agree that something should be put higher, below the query-params, but maybe some minor adjustment should be done to the text too, to be more explicit about direction affecting both the sort-order of the results, and also which log-lines are chosen (i understand those two things are one thing technically, but the effect can be observed at two places)