Write and Query Time Series Data with HiTSDB Java SDK - Time Series Database

This topic shows you how to write and query time series data using the TSDB Java SDK. Read Terms and the HTTP API Reference before you start.

Write data

The Point class represents a time series data point. Use the put method on an HiTSDB client to write points to the database.

The following example writes one data point per second for one hour:

package com.aliyun.hitsdb.client.example;

import java.io.IOException;

import com.aliyun.hitsdb.client.HiTSDB;
import com.aliyun.hitsdb.client.HiTSDBClientFactory;
import com.aliyun.hitsdb.client.HiTSDBConfig;
import com.aliyun.hitsdb.client.value.request.Point;

public class TestWrite {
    public static void main(String[] args) throws InterruptedException, IOException {
        // Connect to HiTSDB
        HiTSDBConfig config = HiTSDBConfig.address("example.hitsdb.com", 8242).config();
        HiTSDB tsdb = HiTSDBClientFactory.connect(config);

        // Write one data point per second for 3,600 seconds
        for (int i = 0; i < 3600; i++) {
            Point point = Point.metric("test").tag("V", "1.0").value(System.currentTimeMillis(), 123.4567).build();
            Thread.sleep(1000);
            tsdb.put(point);
        }

        // Close the client to flush buffered writes and prevent data loss
        tsdb.close();
    }
}

Parameter	Description	Example
`metric`	The metric name for the data point	`"test"`
`tag`	A key-value pair used to filter and group data	Key: `"V"`, Value: `"1.0"`
`value`	The timestamp (in milliseconds) and the numeric value	`System.currentTimeMillis()`, `123.4567`

Important

Always call tsdb.close() when finished. The client buffers writes asynchronously — skipping close() may cause data loss.

Query data

The Query class defines query conditions. Build a Query object with a time range and one or more SubQuery entries, then pass it to the query method.

The following example queries one hour of data for the test metric:

package com.aliyun.hitsdb.client.example;

import java.io.IOException;
import java.util.List;

import com.aliyun.hitsdb.client.HiTSDB;
import com.aliyun.hitsdb.client.HiTSDBClientFactory;
import com.aliyun.hitsdb.client.HiTSDBConfig;
import com.aliyun.hitsdb.client.value.request.Query;
import com.aliyun.hitsdb.client.value.request.SubQuery;
import com.aliyun.hitsdb.client.value.response.QueryResult;
import com.aliyun.hitsdb.client.value.type.Aggregator;

public class TestRead {
    public static void main(String[] args) throws IOException {
        // Connect to HiTSDB
        HiTSDBConfig config = HiTSDBConfig.address("example.hitsdb.com", 8242).config();
        HiTSDB tsdb = HiTSDBClientFactory.connect(config);

        long now = System.currentTimeMillis();

        // Build a query for the last hour, with no aggregation
        Query query = Query.timeRange(now - 3600 * 1000, now)
                .sub(SubQuery.metric("test").aggregator(Aggregator.NONE).tag("V", "1.0").build())
                .build();

        // Run the query and print results
        List<QueryResult> result = tsdb.query(query);
        System.out.println(result);

        // Close the client to prevent data loss
        tsdb.close();
    }
}

Parameter	Description	Example
`timeRange(start, end)`	The query time range in milliseconds	`now - 3600 * 1000` to `now`
`metric`	The metric name to query	`"test"`
`aggregator`	The aggregation function applied to data points	`Aggregator.NONE`
`tag`	Filters results to data points with matching tags	Key: `"V"`, Value: `"1.0"`

Production considerations

When using TSDB in production, keep the following in mind:

Connection reuse: Reuse the HiTSDB client across requests rather than creating a new instance per write or query. Creating a connection per operation adds unnecessary latency.
Safe shutdown: Always call tsdb.close() before your application exits to flush any buffered writes.

What's next

Terms — Key concepts for working with TSDB
HTTP API Reference — Full API documentation for TSDB