promQL API end points

Question

As per the documentation here, there are 2 API end points for querying, one for range queries (GET /api/v1/query_range) and one for instant queries (GET /api/v1/query)

At the same time, I have been posting queries like this to the instant API end point:

metric_name{db='cpu',  category='db'}[5m]

which return range vectors (matrix result type) as the query above has a duration specified. I am assuming that since the query requires a range vector result, this is what is returned although the API end point is for an instant query. The start time is 5 minutes prior to the execution time which could be specified in the 'time' URL param to the API which in effect is also the end time. Not quite clear on what the step is, I am guessing it is collecting all available raw data points?

Is this breakdown of what is happening correct?

Answer 1

The /api/v1/query returns multiple data points per series if the query ends with square brackets. There are two cases exist:

• If the query doesn't contain functions or operators and only contains time series selector. For example, foo{bar="baz"}[5m] . In this case raw samples for the selected time series are returned on the time range (time-5m ... time], where time is a query arg passed to /api/v1/query.
• If the query contains functions or operators. For example, count(foo{bar="baz"})[5m:]. In this case calculated data points are returned on the time range (time-5m ... time] with default step value. The step can be passed explicitly in the query after the colon in square brackets. For example, count(m)[5m:10s] would return calculated data points with step=10s. Such queries are called subqueries in Prometheus ecosystem.

See more details on how to analyze raw Prometheus data with external tools in this article.