Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

prometheusQueryRange

View as MarkdownEdit this pageReport an issueSet up docs MCP

Evaluates a prometheus query using data from a TimeSeries table over a range of evaluation times.

Syntax

prometheusQueryRange('db_name', 'time_series_table', 'promql_query', start_time, end_time, step)
prometheusQueryRange(db_name.time_series_table, 'promql_query', start_time, end_time, step)
prometheusQueryRange('time_series_table', 'promql_query', start_time, end_time, step)

Arguments

  • db_name - The name of the database where a TimeSeries table is located.
  • time_series_table - The name of a TimeSeries table.
  • promql_query - A query written in PromQL syntax.
  • start_time - The start time of the evaluation range.
  • end_time - The end time of the evaluation range.
  • step - The step used to iterate the evaluation time from start_time to end_time (inclusively).

Returned value

The function can returns different columns depending on the result type of the query passed to parameter promql_query:

Result Type Result Columns Example
vector tags Array(Tuple(String, String)), timestamp TimestampType, value ValueType prometheusQuery(mytable, ‘up’)
matrix tags Array(Tuple(String, String)), time_series Array(Tuple(TimestampType, ValueType)) prometheusQuery(mytable, ‘up[1m]’)
scalar scalar ValueType prometheusQuery(mytable, ‘1h30m’)
string string String prometheusQuery(mytable, ‘“abc”’)

Supported PromQL Features

Selectors

Instant selectors, range selectors, label matchers (=, !=, =~, !~), offset modifiers, @ timestamp modifiers, and subqueries.

Functions

Category Functions
Range rate, irate, delta, idelta, increase, last_over_time, deriv, changes, resets
Math abs, sgn, floor, ceil, sqrt, exp, ln, log2, log10, rad, deg, round, clamp, clamp_min, clamp_max
Trig sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh
DateTime day_of_week, day_of_month, days_in_month, day_of_year, minute, hour, month, year
Label label_replace, label_join
Type scalar, vector
Histogram histogram_quantile
Other time, pi, absent

Note: histogram_quantile uses linear interpolation on classic histogram buckets (identified by the le label). Native histograms are not supported. The phi (quantile level) argument must be a constant scalar. Expressions that vary per step, such as histogram_quantile(time() / 1000, ...), are rejected with a NOT_IMPLEMENTED exception.

Operators

Arithmetic (+, -, *, /, %, ^, atan2) and comparison (==, !=, <, >, <=, >= with optional bool) binary operators, with on()/ignoring() and group_left()/group_right() modifiers.

Logical set operators and, or, and unless, with on()/ignoring() modifiers.

Unary operators + and -.

Aggregation Operators

sum, avg, min, max, count, count_values, stddev, stdvar, group, quantile, topk, bottomk, limitk — with optional by() or without() modifiers.

Not yet supported

  • Range functions predict_linear, avg_over_time, min_over_time, max_over_time, sum_over_time, count_over_time, quantile_over_time, stddev_over_time, stdvar_over_time, present_over_time, absent_over_time, mad_over_time, first_over_time, ts_of_min_over_time, ts_of_max_over_time, ts_of_last_over_time, ts_of_first_over_time

Example

SELECT * FROM prometheusQueryRange(mytable, 'rate(http_requests{job="prometheus"}[10m])[1h:10m]', now() - INTERVAL 10 MINUTES, now(), INTERVAL 1 MINUTE)
Navigation