TQL
The TQL keyword executes TQL language in SQL. The TQL is Telemetry Query Language, which is an extension for Prometheus's PromQL in GreptimeDB.
EVAL
Syntax
TQL [EVAL | EVALUATE] (start, end, step, [lookback]) expr [AS alias]
The start, end and step are the query parameters just like Prometheus Query API:
start:<rfc3339 | unix_timestamp | expression>: The start timestamp of the query; the range is inclusive of this value.end:<rfc3339 | unix_timestamp | expression>: The end timestamp of the query; the range is inclusive of this value.step:<duration | float>: The query resolution step, specified as adurationor a floating-point number of seconds.lookback:<duration | float>: The maximum lookback duration for evaluation, default is 5 minutes and optional.
expr is the TQL (PromQL) query string.
The optional AS alias clause allows you to provide an alias for the query result. This is useful for giving meaningful names to the output columns.
Examples
Return the per-second rate for all time series with the http_requests_total metric name, as measured over the last 5 minutes:
TQL eval (1677057993, 1677058993, '1m') rate(prometheus_http_requests_total{job="prometheus"}[5m]);
will get a result just like other normal SQL queries.
start and end can also be time expressions that evaluate to constants. For example, to query the past 3 hours:
TQL EVAL (now() - interval '3' hours, now(), '1m')
sum by (namespace, pod) (
increase(kube_pod_container_status_restarts_total[10m:30s])
);
To query data for the past day:
TQL EVAL (
date_trunc('day', now() - interval '1' day),
date_trunc('day', now(),
'1m'
)
sum by (namespace) (
rate(http_requests_total[5m:30s])
);
You can also use value aliasing to give a meaningful name to your query result:
TQL eval (0, 10, '5s') {__name__="test"} AS test_series;
This will return the results with the column named test_series instead of the default column name.
EXPLAIN
EXPLAIN displays both the logical plan and execution plan for a given PromQL query. The syntax is as follows:
TQL EXPLAIN expr;
For example, to explain the PromQL sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50, we can use
TQL EXPLAIN sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50;
Notice that since the given query won't be actually executed, the triple (start, end, step, [lookback]) is not necessary. But you can still provide it like in TQL EVAL:
TQL EXPLAIN (0, 100, '10s') sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50;
The result should be like the following:
+---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| plan_type | plan |
+---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| logical_plan | Sort: node_disk_written_bytes_total.instance ASC NULLS LAST, node_disk_written_bytes_total.ts ASC NULLS LAST
Filter: SUM(prom_rate(ts_range,field,ts)) > Float64(50)
Aggregate: groupBy=[[node_disk_written_bytes_total.instance, node_disk_written_bytes_total.ts]], aggr=[[SUM(prom_rate(ts_range,field,ts))]]
Projection: node_disk_written_bytes_total.ts, prom_rate(ts_range, field, node_disk_written_bytes_total.ts) AS prom_rate(ts_range,field,ts), node_disk_written_bytes_total.instance
Filter: prom_rate(ts_range, field, node_disk_written_bytes_total.ts) IS NOT NULL
Projection: node_disk_written_bytes_total.ts, node_disk_written_bytes_total.instance, field, ts_range
PromRangeManipulate: req range=[0..0], interval=[300000], eval range=[120000], time index=[ts], values=["field"]
PromSeriesNormalize: offset=[0], time index=[ts], filter NaN: [true]
PromSeriesDivide: tags=["instance"]
Sort: node_disk_written_bytes_total.instance DESC NULLS LAST, node_disk_written_bytes_total.ts DESC NULLS LAST
TableScan: node_disk_written_bytes_total projection=[ts, instance, field], partial_filters=[ts >= TimestampMillisecond(-420000, None), ts <= TimestampMillisecond(300000, None)] |
| physical_plan | SortPreservingMergeExec: [instance@0 ASC NULLS LAST,ts@1 ASC NULLS LAST]
SortExec: expr=[instance@0 ASC NULLS LAST,ts@1 ASC NULLS LAST]
CoalesceBatchesExec: target_batch_size=8192
FilterExec: SUM(prom_rate(ts_range,field,ts))@2 > 50
AggregateExec: mode=FinalPartitioned, gby=[instance@0 as instance, ts@1 as ts], aggr=[SUM(prom_rate(ts_range,field,ts))]
CoalesceBatchesExec: target_batch_size=8192
RepartitionExec: partitioning=Hash([Column { name: "instance", index: 0 }, Column { name: "ts", index: 1 }], 32), input_partitions=32
AggregateExec: mode=Partial, gby=[instance@2 as instance, ts@0 as ts], aggr=[SUM(prom_rate(ts_range,field,ts))]
ProjectionExec: expr=[ts@0 as ts, prom_rate(ts_range@3, field@2, ts@0) as prom_rate(ts_range,field,ts), instance@1 as instance]
CoalesceBatchesExec: target_batch_size=8192
FilterExec: prom_rate(ts_range@3, field@2, ts@0) IS NOT NULL
ProjectionExec: expr=[ts@0 as ts, instance@1 as instance, field@2 as field, ts_range@3 as ts_range]
PromInstantManipulateExec: req range=[0..0], interval=[300000], eval range=[120000], time index=[ts]
PromSeriesNormalizeExec: offset=[0], time index=[ts], filter NaN: [true]
PromSeriesDivideExec: tags=["instance"]
RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=1
ExecutionPlan(PlaceHolder)
|
+---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
ANALYZE
TQL also supports ANALYZE keyword to analyze the given PromQL query's execution. The syntax is as follows:
TQL ANALYZE [VERBOSE] (start, end, step) expr;
For example:
TQL ANALYZE (0, 10, '5s') test;
will get a result like
+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| plan_type | plan |
+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Plan with Metrics | CoalescePartitionsExec, metrics=[output_rows=0, elapsed_compute=14.99µs]
PromInstantManipulateExec: range=[0..10000], lookback=[300000], interval=[5000], time index=[j], metrics=[output_rows=0, elapsed_compute=1.08µs]
PromSeriesNormalizeExec: offset=[0], time index=[j], filter NaN: [false], metrics=[output_rows=0, elapsed_compute=1.11µs]
PromSeriesDivideExec: tags=["k"], metrics=[output_rows=0, elapsed_compute=1.3µs]
RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=32, metrics=[send_time=32ns, repart_time=32ns, fetch_time=11.578016ms]
RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=1, metrics=[send_time=1ns, repart_time=1ns, fetch_time=21.07µs]
ExecutionPlan(PlaceHolder), metrics=[]
|
+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Using TQL ANALYZE VERBOSE will get a verbose result of the execution.
TQL ANALYZE VERBOSE (0, 10, '5s') test;