Query data

Updated at:

LindormTSDB supports three ways to query time-series data: SQL, PromQL, and TSDB-compatible APIs and SDKs. SQL is the recommended approach for most use cases. LindormTSDB optimizes SQL queries to improve performance in most scenarios, reduce server resource usage, and improve service stability.

Query with SQL

LindormTSDB extends standard SQL with time-series-specific features including downsampling queries, aggregate queries, and latest-value queries. It also provides a rich set of time-series functions and operators. SQL query execution is powered by Apache Calcite, which provides a broad set of SQL computing and analysis capabilities.

For a full reference of supported SQL syntax, see .

Access methods

Three access methods are available for SQL queries.

MethodBest forProtocol and data formatReference
Java Native SDKJava applicationsJava API — supports streaming data transmission and thread-safe connections; no manual connection management requiredJava Native SDK
JDBC DriverJava applications that use an ORM frameworkJDBC — use Druid or another connection pool manager; requires an Object-Relational Mapping (ORM) frameworkJava JDBC Driver
HTTP SQL APINon-Java applicationsHTTP — results returned in streaming mode; language-agnosticUse the HTTP-based SQL API of LindormTSDB

How SAMPLE BY and GROUP BY work together

LindormTSDB uses the SAMPLE BY clause for time-series downsampling and the GROUP BY clause for aggregating across multiple time series. The two clauses cannot be combined at the same query level — use GROUP BY in an outer query wrapping a SAMPLE BY subquery.

Downsample a single time series

The following query downsamples humidity readings for a specific device at 8-hour intervals:

SELECT device_id, region, time, count(humidity) AS count_humidity
FROM sensor
WHERE device_id = 'F07A1260'
SAMPLE BY 8h;

Downsample multiple time series, then aggregate

The following query downsamples all devices at 8-hour intervals in a subquery, then aggregates the results by device ID in the outer query:

SELECT device_id, max(avg_humidity) AS max_humidity
FROM (
  SELECT device_id, region, time, avg(humidity) AS avg_humidity
  FROM sensor
  SAMPLE BY 8h
)
GROUP BY device_id;

For more information, see:

Query with PromQL

LindormTSDB supports PromQL query capability, enabling Prometheus-compatible query workflows against time-series data stored in Lindorm.

Query with TSDB-compatible APIs and SDKs

LindormTSDB is compatible with more than 90% of TSDB capabilities, so you can generally migrate TSDB applications to LindormTSDB with minimal changes. We recommend migrating your queries to SQL for better long-term performance.

Key mapping: metrics and tables

In TSDB, data is organized by metric name. In LindormTSDB, metrics map to tables. When querying data written via the HTTP SQL API, Java Native SDK, line protocol, or TSDB-compatible multi-value operations, set the metric in metric@field format:

  • metric — the table name

  • field — the column name storing the target data

Query multi-value data

Multi-value data written through any of the following methods can be queried using TSDB-compatible operations:

  • TSDB-compatible API operations

  • HTTP SQL API

  • Java Native SDK

  • line protocol

For step-by-step instructions, see:

Query single-value data

Single-value data written using TSDB-compatible API operations can be queried via the same TSDB-compatible API operations. This approach is not recommended for new development — use SQL queries instead. When using a single-value query to read multi-value data written through TSDB-compatible multi-value APIs, the HTTP SQL API, the Java Native SDK, or the line protocol, specify the metric as metric@field (metric is the table name and field is the column name).

For reference, see:

Query with Grafana

Use Grafana to visualize large volumes of time-series data from LindormTSDB. Two Grafana plug-ins are supported.

Alibaba Cloud Lindorm data source plug-in

The Alibaba Cloud Lindorm data source plug-in lets you query LindormTSDB using auto-generated or custom SQL statements directly in the Grafana query editor. See Use Grafana to access LindormTSDB.

OpenTSDB data source plug-in

LindormTSDB exposes OpenTSDB-compatible API operations, so you can connect the OpenTSDB data source plug-in in Grafana to query time-series data in Lindorm.

When querying data written via the HTTP SQL API, Java Native SDK, line protocol, or TSDB-compatible multi-value operations through this plug-in, set metrics in metric@field format as described in Key mapping: metrics and tables.

Improve query performance

LindormTSDB provides two mechanisms for improving query performance at scale. The right choice depends on your query pattern and how data is stored.

MethodHow it worksBest forEffect on data storage
Pre-aggregationUses continuous queries to pre-compute query results and store them in a result table. Query the result table to retrieve results quickly.Real-time aggregation across a large number of time seriesPre-aggregated results are stored in a separate table from the original table. Specify the result table when querying.
Pre-downsamplingThe storage engine stores written data at lower precision. At query time, LindormTSDB automatically selects the pre-downsampled data whose precision is closest to the interval specified in the query, then aggregates the data. This reduces the amount of data processed in real time and lowers query latency.Queries spanning wide time rangesPre-downsampled data and original data are stored in the same table. The engine selects the closest pre-downsampled data automatically, so you do not need to query a separate table.

For detailed configuration, see Continuous queries and Pre-downsampling.