PromQL Support

Circonus' CAQL engine supports the PromQL query language through use of the #lang directive. Anywhere that supports a CAQL query can utilize this to run PromQL queries instead. The engine will translate the PromQL into CAQL, and execute it.

#lang="promql" http_requests_total{job="apiserver", handler="/api/comments"}

Supported Functions

Below you'll find the PromQL functions that we directly support and their CAQL equivalents. CAQL find is used to fetch the data in most cases (any exceptions are marked below). To emulate the staleness behavior of PromQL ("lookback delta"), the data from the fetch/find is piped through the CAQL function fill:forward with the 5m default (which can be overridden using the CAQL #lookback_window directive).

PromQL Function	CAQL Equivalent	Notes
`arithmetic operators (+-*/%^)`	`op:add,sub,prod,div2,mod,exp`
`@ modifier`	`find(..., start_time_override=<@_time>)`
`# comment`	`(treated as whitespace, but beware of conflicts with CAQL directives)`
`vector to scalar filter comparison (==,!=,>,<,>=,<=)`	`filter:values:eq,not:eq,gt,lt,geq,leq([scalar])`
`vector to scalar bool comparison (==,!=,>,<,>=,<= bool)`	`op:eq,not(eq),gt,lt,geq,leq([scalar])`
`abs(instant_vector)`	`math:abs`
`absent(instant_vector)`	`stats:absent`
`absent_over_time(range_vector)`	`rolling:absent`
`acos, acosh(instant_vector)`	`math:acos,acosh`
`asin, asinh(instant_vector)`	`math:asin,asinh`
`atan, atanh(instant_vector)`	`math:atan,atanh`
`avg(instant_vector)`	`stats:mean`
`avg by (labels) (instant_vector)`	`group_by:mean`
`avg_over_time(range_vector)`	`rolling:mean`
`bottomk(n, instant_vector)`	`opt:fetch(numeric, average, "bottomk, n")`
`ceil(instant_vector)`	`math:ceil`
`changes(range_vector)`	`rolling:changes`
`clamp, clamp_max, clamp_min(instant_vector, [min, max])`	`stats:clamp`
`cos, cosh(instant_vector)`	`math:cos,cosh`
`count(instant_vector)`	`stats:count`
`count by (labels) (instant_vector)`	`group_by:count`
`count_over_time(range_vector)`	`rolling:count`
`day_of_month(instant_vector)`	`time:tz("UTC", "monthday")`
`day_of_week(instant_vector)`	`time:tz("UTC", "weekday")`
`day_of_year(instant_vector)`	`time:tz("UTC", "yearday")`
`deg(instant_vector)`	`math:deg`
`delta(range_vector)`	`rolling:delta`
`deriv(range_vector)`	`find:deriv \\| rolling:mean`
`exp(instant_vector)`	`math:exp`
`floor(instant_vector)`	`math:floor`
`group(instant_vector)`	`stats:alwaysone`
`group by (labels) (instant_vector)`	`group_by:alwaysone`
`histogram_count(histogram_instant_vector)`	`find:histogram \\| histogram_count`
`histogram_fraction(lower, upper, histogram_instant_vector)`	`find:histogram \\| histogram:ratio_between`
`histogram_quantile(n, histogram_instant_vector)`	`find:histogram \\| histogram:percentile`
`histogram_sum(histogram_instant_vector)`	`find:histogram \\| histogram:sum`
`hour(instant_vector)`	`time:tz("UTC", "hour")`
`idelta(range_vector)`	`rolling:delta`	aliased to delta
`increase(range_vector)`	`rolling:increase`
`irate(range_vector)`	`find:counter \\| rolling:mean`	aliased to rate
`last_over_time(range_vector)`	`rolling:last`
`ln(instant_vector)`	`math:ln`
`log2(instant_vector)`	`math:log2`
`log10(instant_vector)`	`math:log10`
`max(instant_vector)`	`stats:max`
`max by (labels) (instant_vector)`	`group_by:max`
`max_over_time(range_vector)`	`rolling:max`
`min(instant_vector)`	`stats:min`
`min by (labels) (instant_vector)`	`group_by:min`
`min_over_time(range_vector)`	`rolling:min`
`minute(instant_vector)`	`time:tz("UTC", "minute")`
`month(instant_vector)`	`time:tz("UTC", "month")`
`offset`	`find(..., start_time_offset=<offset_duration>)`
`pi`	`math:pi`
`present_over_time(range_vector)`	`rolling:present`
`quantile(n, instant_vector)`	`stats:percentile`
`quantile_over_time(n, range_vector)`	`rolling:percentile`
`rad(instant_vector)`	`math:rad`
`rate(range_vector)`	`find:counter \\| rolling:mean`
`resets(range_vector)`	`rolling:resets`
`round(instant_vector, to_nearest)`	`math:round`
`sgn(instant_vector)`	`math:sgn`
`sin, sinh(instant_vector)`	`math:sin,sinh`
`sqrt(instant_vector)`	`math:sqrt`
`stddev(instant_vector)`	`stats:stddev`
`stddev by (labels) (instant_vector)`	`group_by:stddev`
`stddev_over_time(range_vector)`	`rolling:stddev`
`stdvar(instant_vector)`	`stats:popvar`
`stdvar by (labels) (instant_vector)`	`group_by:popvar`
`stdvar_over_time(range_vector)`	`rolling:popvar`
`sum(instant_vector)`	`stats:sum`
`sum by (labels) (instant_vector)`	`group_by:sum`
`sum_over_time(range_vector)`	`rolling:sum`
`tan, tanh(instant_vector)`	`math:tan,tanh`
`time`	`time:epoch`
`timestamp(instant_vector)`	`(directly supported)`
`topk(n, instant_vector)`	`opt:fetch(numeric, average, "topk, n")`
`year(instant_vector)`	`time:tz("UTC", "year")`

Functions Not Yet Supported

The following PromQL functions are not currently available in CAQL but may be implemented in the future.

PromQL Function
`vector to vector comparison (==,!=,>,<,>=,<=)`
`and`
`atan2`
`count_values(value_label, instant_vector)`
`days_in_month(instant_vector)`
`group_left`
`group_right`
`holt_winters(range_vector, smoothing_factor, trend_factor)`
`ignoring`
`label_join(instant_vector, dst_label, separator, src_label_1, src_label_2, ...)`
`label_replace(instant_vector, dst_label, replacement, src_label, regex)`
`on`
`or`
`predict_linear(range_vector, t)`
`quantile by (labels) (n, instant_vector)`
`scalar(instant_vector)`
`sort(instant_vector)`
`sort_desc(instant_vector)`
`unless`
`vector(scalar)`
`without`

PromQL Support

Supported Functions​

Functions Not Yet Supported​

Supported Functions

Functions Not Yet Supported