Query data
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.
| Method | Best for | Protocol and data format | Reference |
|---|---|---|---|
| Java Native SDK | Java applications | Java API — supports streaming data transmission and thread-safe connections; no manual connection management required | Java Native SDK |
| JDBC Driver | Java applications that use an ORM framework | JDBC — use Druid or another connection pool manager; requires an Object-Relational Mapping (ORM) framework | Java JDBC Driver |
| HTTP SQL API | Non-Java applications | HTTP — results returned in streaming mode; language-agnostic | Use 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 namefield— 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 a multivariate data point — using API operations
Use the SDK multi-value data model to read data — using SDKs
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 single-value data points — using API operations
Query data — using SDKs
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.
| Method | How it works | Best for | Effect on data storage |
|---|---|---|---|
| Pre-aggregation | Uses 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 series | Pre-aggregated results are stored in a separate table from the original table. Specify the result table when querying. |
| Pre-downsampling | The 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 ranges | Pre-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.