Skip to main content
Version: nightly

Prometheus Query Language

GreptimeDB can be used as a drop-in replacement for Prometheus in Grafana, because GreptimeDB supports PromQL (Prometheus Query Language). GreptimeDB has reimplemented PromQL natively in Rust and exposes the ability to several interfaces, including the HTTP API of Prometheus, the HTTP API of GreptimeDB, and the SQL interface.

Prometheus' HTTP API

GreptimeDB has implemented a set of Prometheus compatible APIs under HTTP context /v1/prometheus/:

  • Instant queries /api/v1/query
  • Range queries /api/v1/query_range
  • Series /api/v1/series
  • Label names /api/v1/labels
  • Label values /api/v1/label/<label_name>/values

It shares same input and output format with original Prometheus HTTP API. You can also use GreptimeDB as an in-place replacement of Prometheus. For example in Grafana Prometheus data source, set http://localhost:4000/v1/prometheus/ as context root of Prometheus URL.

Consult Prometheus documents for usage of these API.

You can use additional query parameter db to specify GreptimeDB database name.

GreptimeDB's HTTP API

GreptimeDB also exposes an custom HTTP API for querying with PromQL, and returning GreptimeDB's data frame output. You can find it on /promql path under the current stable API version /v1, in GreptimeDB HTTP API Port. For example:

curl -X GET \
-H 'Authorization: Basic {{authorization if exists}}' \
-G \
--data-urlencode 'db=public' \
--data-urlencode 'query=avg(system_metrics{idc="idc_a"})' \
--data-urlencode 'start=1667446797' \
--data-urlencode 'end=1667446799' \
--data-urlencode 'step=1s' \
http://localhost:4000/v1/promql

The input parameters are similar to the range_query in Prometheus' HTTP API:

  • db=<database name>: Required when using GreptimeDB with authorization, otherwise can be omitted if you are using the default public database.
  • query=<string>: Required. Prometheus expression query string.
  • start=<rfc3339 | unix_timestamp>: Required. The start timestamp, which is inclusive. It is used to set the range of time in TIME INDEX column.
  • end=<rfc3339 | unix_timestamp>: Required. The end timestamp, which is inclusive. It is used to set the range of time in TIME INDEX column.
  • step=<duration | float>: Required. Query resolution step width in duration format or float number of seconds.

Here are some examples for each type of parameter:

  • rfc3339
    • 2015-07-01T20:11:00Z (default to seconds resolution)
    • 2015-07-01T20:11:00.781Z (with milliseconds resolution)
    • 2015-07-02T04:11:00+08:00 (with timezone offset)
  • unix timestamp
    • 1435781460 (default to seconds resolution)
    • 1435781460.781 (with milliseconds resolution)
  • duration
    • 1h (1 hour)
    • 5d1m (5 days and 1 minute)
    • 2 (2 seconds)
    • 2s (also 2 seconds)

The result format is the same as /sql interface described in Query Data.

{
"code": 0,
"output": [
{
"records": {
"schema": {
"column_schemas": [
{
"name": "ts",
"data_type": "TimestampMillisecond"
},
{
"name": "AVG(system_metrics.cpu_util)",
"data_type": "Float64"
},
{
"name": "AVG(system_metrics.memory_util)",
"data_type": "Float64"
},
{
"name": "AVG(system_metrics.disk_util)",
"data_type": "Float64"
}
]
},
"rows": [
[
1667446798000,
80.1,
70.3,
90
],
[
1667446799000,
80.1,
70.3,
90
]
]
}
}
],
"execution_time_ms": 5
}

SQL

GreptimeDB also extends SQL grammar to support PromQL. You can start with the TQL (Time-series Query Language) keyword to write parameters and queries. The grammar looks like this:

TQL [EVAL|EVALUATE] (<START>, <END>, <STEP>) <QUERY>

<START> specifies the query start range and <END> specifies the end time. <STEP> identifies the query resolution step width. All of them can either be an unquoted number (represent UNIX timestamp for <START> and <END>, and duration in seconds for <STEP>), or a quoted string (represent an RFC3339 timestamp for <START> and <END>, and duration in string format for <STEP>).

For example:

TQL EVAL (1676738180, 1676738780, '10s') sum(some_metric)

You can write the above command in all places that support SQL, including the GreptimeDB HTTP API, SDK, PostgreSQL and MySQL client etc.

Multiple fields

Based on the table model, GreptimeDB supports multiple fields in a single table(or metric, in the context of Prometheus). Queries will run on every fields by default. Or you can use the special filter __field__ to query a specific field(s):

metric{__field__="field1"}

Exclude or regex are also supported:

metric{__field__!="field1"}

metric{__field__=~"field_1|field_2"}

metric{__field__!~"field_1|field_2"}

Limitations

Though GreptimeDB supports a rich set of data types, the PromQL implementation is still limited to the following types:

  • timestamp: Timestamp
  • tag: String
  • value: Double

Currently only a subset of PromQL is supported. Here attaches the compatibility list. You can also check our latest compliance report in this tracking issue.

Literal

Both string and float literals are supported, with the same rule as PromQL.

Selector

Both instant and range selector are supported. The only exception is the label matching on metric name, e.g.: {__name__!="request_count}" (but the equal-matching case is supported: {__name__="request_count}").

Time duration and offset are supported, but @ modifier is not supported yet.

Timestamp precision

The timestamp precision in PromQL is limited by its query syntax, only supporting calculations up to millisecond precision. However, GreptimeDB supports storing high-precision timestamps, such as microseconds and nanoseconds. When using PromQL for calculations, these high-precision timestamps are implicitly converted to millisecond precision.

Binary

Pure literal binary-expr like 1+1 is not supported yet.

  • Supported:

    OperatorExample
    adda + b
    suba - b
    mula * b
    diva / b
    moda % b
    eqlca == b
    neqa != b
    gtra > b
    lssa < b
    gtea >= b
    ltea <= b
  • Unsupported:

    OperatorProgress
    powerTBD
    atan2TBD
    andTBD
    orTBD
    unlessTBD

Aggregators

  • Supported:

    AggregatorExample
    sumsum by (foo)(metric)
    avgavg by (foo)(metric)
    minmin by (foo)(metric)
    maxmax by (foo)(metric)
    stddevstddev by (foo)(metric)
    stdvarstdvar by (foo)(metric)
  • Unsupported:

    AggregatorProgress
    countTBD
    groupingTBD
    topkTBD
    bottomkTBD
    count_valuesTBD

Instant Functions

  • Supported:

    FunctionExample
    absabs(metric)
    ceilceil(metric)
    expexp(metric)
    lnln(metric)
    log2log2(metric)
    log10log10(metric)
    sqrtsqrt(metric)
    acosacos(metric)
    asinasin(metric)
    atanatan(metric)
    sinsin(metric)
    coscos(metric)
    tantan(metric)
    acoshacosh(metric)
    asinhasinh(metric)
    atanhatanh(metric)
    sinhsinh(metric)
    coshcosh(metric)
    scalarscalar(metric)
    tanhtanh(metric)
    timestamptimestamp()
    histogram_quantilehistogram_quantile(phi, metric)
  • Unsupported:

    FunctionProgress / Example
    absentTBD
    sgnTBD
    sortTBD
    sort_descTBD
    degTBD
    radTBD
    other multiple input fnsTBD

Range Functions

  • Supported:
    FunctionExample
    ideltaidelta(metric[5m])
    <aggr>_over_timecount_over_time(metric[5m])
    stddev_over_timestddev_over_time(metric[5m])
    stdvar_over_timestdvar_over_time(metric[5m])
    changeschanges(metric[5m])
    deltadelta(metric[5m])
    raterate(metric[5m])
    derivderiv(metric[5m])
    increaseincrease(metric[5m])
    irateirate(metric[5m])
    resetreset(metric[5m])