Skip to content
ClickHouse Docs
49.6kGet Started

prometheusQuery

View as MarkdownEdit this pageReport an issueSet up docs MCP

Autogenerated from ClickHouse system tables

Evaluates a prometheus query using data from a TimeSeries table.

Syntax

prometheusQuery('db_name', 'time_series_table', 'promql_query', evaluation_time)
prometheusQuery(db_name.time_series_table, 'promql_query', evaluation_time)
prometheusQuery('time_series_table', 'promql_query', evaluation_time)

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.
  • evaluation_time - The evaluation timestamp, with millisecond or finer precision. To evaluate a query at the current time, use now() as evaluation_time.

Returned value

The function 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 DateTime64(S, TZ), value Float64 prometheusQuery(mytable, ‘up’)
matrix tags Array(Tuple(String, String)), samples Array(Tuple(DateTime64(S, TZ), Float64)) prometheusQuery(mytable, ‘up[1m]’)
scalar timestamp DateTime64(S, TZ), value Float64 prometheusQuery(mytable, ‘1h30m’)
string timestamp DateTime64(S, TZ), value String prometheusQuery(mytable, ‘“abc”’)

The values are always Float64 regardless of the type of the values in the TimeSeries table. The scale S of the timestamps is the scale of the timestamps in the table, but not less than 3 (milliseconds). The time zone TZ is the time zone of evaluation_time if it has type DateTime or DateTime64 with a time zone, otherwise it is the time zone of the timestamps in the table.

The samples column is named time_series if the TimeSeries table has version 2 or earlier.

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, first_over_time, sum_over_time, avg_over_time, count_over_time, max_over_time, min_over_time, ts_of_max_over_time, ts_of_min_over_time, ts_of_last_over_time, ts_of_first_over_time, deriv, changes, resets, present_over_time, absent_over_time, quantile_over_time, mad_over_time, predict_linear
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.

Note: ts_of_min_over_time, ts_of_max_over_time, ts_of_last_over_time, first_over_time, ts_of_first_over_time and mad_over_time are experimental functions in Prometheus (enabled there with --enable-feature=promql-experimental-functions); ClickHouse evaluates them without requiring that flag.

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 stddev_over_time, stdvar_over_time

Example

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